Repository navigation
feat(agent): local Web Bot Auth verification in detectBot() (#323) - #10
Merged
Merged
Conversation
…/app#323) Verify inbound AI-agent signatures (RFC 9421 HTTP Message Signatures, tag "web-bot-auth") locally in middleware — on Node and every WinterCG edge runtime — with no API key and zero network on the warm path. - New agent/ module: a zero-dep RFC 8941 SFV parser, RFC 9421 signature-base construction, JWK-thumbprint keyids (RFC 7638/8037), and a cached, curated directory client (Ed25519 + RSA-PSS-SHA512 via WebCrypto). Curated-only, so a request's Signature-Agent header never selects a fetch target (no SSRF); stale-while-revalidate keeps the warm path off the network. - WebDecoy.detectBot(request) — returns a verdict (verified / impersonation / claimed / none) with agent name+category for verified agents. Accepts a WHATWG Request or { method, url, headers }. - webBotAuth() rule — denies impersonation of known agents by default; the verdict is precomputed async into RuleContext.agent (same pattern as filter rules + IP enrichment) so the sync rule can act on it. Surfaced on ProtectResult.agent. - Verdict taxonomy matches the ingest verifier (WebDecoy/app#320) and the edge validator; curated directory list tracks backend signed_agents.go. Tests: signed→verified, tamper/expiry→impersonation, unknown-key/host-unbound →claimed, none; warm-path p95 < 5ms; RFC 7638 thumbprint KAT; and full verification running inside a real Vercel Edge Runtime VM.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements WebDecoy/app#323 — local Web Bot Auth verification in the Node SDK. Part of the Agent Identity & Trust Layer milestone (app#331); the SDK half of Phase 2 FR5, and it upgrades the Vercel bot-detection story (app#284/#299) from parity to lead.
What it does
AI agents (OpenAI Operator, ChatGPT, the IETF
webbotauthcohort) cryptographically sign their requests (RFC 9421, tagweb-bot-auth). This verifies those signatures in-process, on Node and every WinterCG edge runtime — no API key, zero network on the warm path.Two entry points:
wd.detectBot(request)— returns a verdict; the developer decides. Accepts a WHATWGRequest(edge/Next.js) or{ method, url, headers }(Node).webBotAuth()rule — drops into the rules engine and denies impersonation of known agents by default. The verdict is precomputed async intoRuleContext.agent(the same pattern filter rules use for IP enrichment), so the sync rule can act on it. Also surfaced onProtectResult.agent.Verdict taxonomy (matches ingest app#320 + the edge validator)
verifiedimpersonationclaimednoneDesign
agent/module, zero deps: RFC 8941 SFV parser, RFC 9421 signature base, JWK-thumbprint keyids (RFC 7638/8037), WebCrypto Ed25519 + RSA-PSS-SHA512.signed_agents.go); a request's ownSignature-Agentheader never selects a fetch target, so there's no SSRF surface. Stale-while-revalidate cache keeps verification off the network once warm.Acceptance criteria
webBotAuth()rule,onImpersonation: 'DENY'default@edge-runtime/vm;check:edgepassesdocs/verify-ai-agents-web-bot-auth.md("Verify AI agents with Web Bot Auth in Next.js")Tests
packages/webdecoy/src/agent/web-bot-auth.test.ts(signatures built by hand from the RFC base, so a base-construction bug fails verification rather than passing): verified, tamper→impersonation, expiry→impersonation, unknown-key→claimed, host-unbound→claimed, none, Node{method,url,headers}path, warm p95<5ms, RFC 7638 thumbprint KAT. Plus thewebBotAuthrule unit tests and the Edge-VM case. Full suite: 129 passing, all packages build, both@webdecoy/nodeand@webdecoy/nextjsedge-compatible.