feat: Web Bot Auth cryptographic verification (0.14.0)

Cloudflare's post introducing this mechanism is titled 'Forget IPs: using
cryptography to verify bot and agent traffic'. The published-IP-range check
shipped in 0.11 is precisely the method it retires, so the library should
implement the successor rather than defend the predecessor.

Web Bot Auth is an RFC 9421 HTTP Message Signatures profile — Ed25519 per
request, a Signature-Agent header naming the key directory, keys at
/.well-known/http-message-signatures-directory. Backed by Cloudflare, Amazon,
Akamai and OpenAI, IETF working group chartered 2026. It dominates ranges on
every axis that bit us: any agent that signs rather than four vendors, no
freshness problem, no false 'spoofed' from a stale list, and it covers agents
running on a user's own machine — the case ranges structurally cannot.

Adds combinedVerifier(), which prefers a signature and falls back to ranges,
so adoption shifts the mix with no change at the call site.

Two deliberate rules:

- A present-but-invalid signature returns 'spoofed' even when the client IP
  sits in a published range. Otherwise a forged signature could be laundered
  into 'verified' by the weaker check.
- Unsigned traffic is 'unverifiable', never 'spoofed'. Most agents do not sign
  yet; treating silence as forgery would mislabel nearly all real traffic.

Unsigned requests return before any I/O — the common path today costs nothing.
Signed ones fetch the signer's directory once per origin and cache it, keyed by
origin, for an hour.

Structured-field parsing is scoped to the shapes this profile emits rather
than a full RFC 8941 implementation, and returns null rather than guessing:
a malformed header must never read as a valid signature.

Tests 246 -> 262. The suite generates a real Ed25519 keypair and signs the
actual signature base, then checks replay onto another path, a tampered
signature, a key absent from the directory, expiry both by `expires` and by
maxAge, non-https signers, an unreachable directory, allowedSigners, that
unsigned traffic triggers no fetch, and that the directory is cached. Fixture
signatures would only have encoded whatever the parser happens to do.

Author: Gdewilde

README.md

@@ -82,6 +82,38 @@ Now you can build:
 
 ---
 
+## Cryptographic verification (Web Bot Auth)
+
+Published IP ranges were always the weak form of identity. [Web Bot
+Auth](https://blog.cloudflare.com/web-bot-auth/) is the strong one: an RFC 9421
+HTTP Message Signatures profile where an agent signs each request with Ed25519
+and publishes its keys at a well-known directory. Backed by Cloudflare, Amazon,
+Akamai and OpenAI, with an IETF working group chartered in 2026.
+
+```ts
+import { combinedVerifier } from '@apideck/agent-analytics/verify'
+
+void trackVisit(req, { analytics, verify: combinedVerifier() })
+```
+
+`combinedVerifier` prefers the signature and falls back to ranges:
+
+| | published IP ranges | Web Bot Auth |
+| --- | --- | --- |
+| Coverage | 4 vendors | any agent that signs |
+| Freshness | rots; needs weekly refresh | none needed |
+| False `spoofed` | stale list accuses real crawlers | impossible |
+| Agents on a user's machine | unverifiable | signable |
+
+A present-but-invalid signature is decisive: it returns `spoofed` even if the
+client IP happens to sit in a published range, so a forged signature cannot be
+laundered by the weaker check. Unsigned traffic is `unverifiable`, never
+`spoofed` — most agents do not sign yet, and treating silence as forgery would
+mislabel nearly all real traffic.
+
+Unsigned requests cost nothing: the check returns before any I/O. Signed ones
+fetch the signer's key directory once per origin and cache it for an hour.
+
 ## Upgrading to 0.12
 
 Four breaking changes, all deliberate. Each one existed because the previous

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apideck/agent-analytics",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Track AI agent and bot traffic to your Next.js / Vercel app — PostHog, webhooks, or any custom analytics backend. Detects Claude, ChatGPT, Perplexity, Google-Extended, and more.",
   "keywords": [
     "ai",

src/track.ts

@@ -80,7 +80,9 @@ export async function trackVisit(req: Request, opts: TrackVisitOptions): Promise
     // Verification is injected rather than imported, so the published IP range
     // tables only reach bundles that actually use them. Import `verifyRequest`
     // from `@apideck/agent-analytics/verify` and pass it as `verify`.
-    const verification = opts.verify ? opts.verify(req) : null
+    // May be async: Web Bot Auth fetches a signer's key directory on first
+    // sight of that origin, then serves from cache.
+    const verification = opts.verify ? await opts.verify(req) : null
 
     // Headless scoring only discriminates for browser-shaped UAs. On a declared
     // crawler or an HTTP client it fires on nearly everything — measured true on

src/types.ts

@@ -41,7 +41,7 @@ export interface TrackVisitOptions {
    * Injected rather than imported so the published IP range tables — the
    * largest thing in the package — only reach bundles that use them.
    */
-  verify?: (req: Request) => BotVerificationLike
+  verify?: (req: Request) => BotVerificationLike | Promise<BotVerificationLike>
   /**
    * Label describing how the request arrived (e.g. `'page-view'`, `'md-suffix'`,
    * `'ua-rewrite'`). Emitted as a `source` property on the captured event so

src/verify.ts

@@ -159,3 +159,50 @@ export function clientIpFromRequest(req: Request): string {
 export function verifyRequest(req: Request): BotVerification {
   return verifyBotIdentity(req.headers.get('user-agent'), clientIpFromRequest(req))
 }
+
+export {
+  clearKeyCache,
+  jwkThumbprint,
+  verifyWebBotAuth,
+  webBotAuthVerifier
+} from './webbotauth.js'
+export type { WebBotAuthOptions, WebBotAuthResult, WebBotAuthVerdict } from './webbotauth.js'
+
+import { verifyWebBotAuth, type WebBotAuthOptions } from './webbotauth.js'
+import type { BotVerificationLike } from './types.js'
+
+/**
+ * Verifier that prefers a cryptographic signature and falls back to published
+ * IP ranges.
+ *
+ * Ordering matters. Web Bot Auth proves control of a signing key, works for
+ * any agent that adopts it, and cannot go stale. IP ranges cover four vendors,
+ * rot between refreshes, and cannot see an agent running on a user's own
+ * machine. So a signature — valid or invalid — is always the answer when one
+ * is present; ranges only speak when the request is unsigned.
+ *
+ * As signing adoption grows this quietly shifts from mostly-ranges to
+ * mostly-signatures with no change at the call site.
+ */
+export function combinedVerifier(
+  opts: WebBotAuthOptions = {}
+): (req: Request) => Promise<BotVerificationLike> {
+  return async (req: Request): Promise<BotVerificationLike> => {
+    const signed = await verifyWebBotAuth(req, opts)
+
+    if (signed.verdict === 'verified') {
+      return { verdict: 'verified', verified: true, reason: 'web-bot-auth' }
+    }
+    // A signature that is present and fails is decisive — do not let a lucky
+    // IP-range hit launder a forged signature into 'verified'.
+    if (signed.verdict === 'invalid-signature' || signed.verdict === 'expired') {
+      return { verdict: 'spoofed', verified: false, reason: `web-bot-auth-${signed.verdict}` }
+    }
+
+    const byRange = verifyRequest(req)
+    if (byRange.verdict !== 'not-claimed' && byRange.verdict !== 'unverifiable') {
+      return { ...byRange, reason: byRange.reason ?? 'published-ip-range' }
+    }
+    return byRange
+  }
+}