Knowledge Base
Reference articles explaining how the checker works, what the grades mean, and what Web Bot Auth is.
Articles
- The Ultimate Guide to Web Bot Auth The full story: the standard and its IETF status, who signs and who verifies today, registries, and how to implement it.
- What is Web Bot Auth? A short primer: bots sign HTTP requests with Ed25519 keys, and verifiers check the signature instead of trusting the User-Agent.
- What is a Signature Agent Card? The optional metadata describing the agent behind the signatures, and how it differs from an A2A or MCP agent card.
- How grading works The 3-state verdict (VALID / INVALID / NOT FOUND), letter grades A-F, weighted scoring, and capping rules.
Individual check pages
Every line in a report has a "Why this matters" link that points to
/kb/<check-id>. Each of those pages explains what the
check verifies, how to resolve a failure, and how the checker scores it.
JWKS directory checks
- Directory is a key set The directory body must be a JSON Web Key Set: a JSON object with a "keys" array.
- Directory body is valid JSON The directory response body must parse as JSON before any key-set check can run.
- Directory caching headers A Cache-Control header on the directory response is advisory; the checker warns if it is absent.
- Curve is Ed25519 An OKP key with a curve other than Ed25519 raises an advisory warning: other registered algorithms are spec-legal, but Ed25519 is the deployed baseline.
- Key type is OKP Keys with a kty other than OKP raise an advisory warning: the spec permits other registered algorithms, but Ed25519 (OKP) is the deployed baseline this checker verifies.
- No duplicate key ids No two keys in the directory may share the same kid value.
- No private key material The published directory must contain only public keys. A private key component in any key is a serious leak.
- No published test keys Advisory: a directory key whose private half is printed in RFC 9421 or RFC 8037 raises a warning, because anyone can sign with it.
- Key validity window Optional nbf and exp on a key must be coherent: in seconds, not already expired, already valid, and not an absurdly long window.
- Public key is 32 bytes Every key's x value must be base64url that decodes to exactly 32 bytes.
- Key set is not empty The keys array must contain at least one key.
- Key set size is reasonable An unusually large key set raises a warning; the checker uses a sanity bound of 100 keys.
- Key id and thumbprint At the well-known path a key's kid is optional, but when present it must be the key's RFC 7638 thumbprint. The checker warns on any other kid and passes keys without one.
- Directory media type The directory should be served as application/http-message-signatures-directory+json; a generic JWKS type warns, anything else fails.
- Directory response self-signature The directory response should carry its own HTTP Message Signatures, one per key, covering the request authority and the Content-Digest of the body, so verifiers can ignore mirrored or misattributed key sets. Advisory.
- Directory endpoint reachable The directory endpoint must answer with an HTTP 2xx response; an unreachable or non-2xx endpoint means there is no directory. A bot-protection challenge gets its own message.
- Directory served over HTTPS The directory must be served over HTTPS; a plaintext HTTP directory fails and caps the grade at D.
- Directory served directly with 200 Advisory: verifiers accept the directory only from a direct HTTP 200 response and do not follow redirects. The checker warns when it reached the directory through a redirect or got a 2xx status other than 200.
Signature checks
- Signature-Agent header Every signed request must carry a Signature-Agent header: a structured-field dictionary whose members are https URIs. For the default directory type the value is an origin. A missing or malformed header fails; the legacy string form warns.
- Created time not in the future The created timestamp must not be in the future beyond a small clock-skew allowance.
- Ed25519 signature verifies The Ed25519 signature must verify against the resolved directory public key. This is the core cryptographic check.
- Signature not expired The expires timestamp must not already be in the past beyond a small clock-skew allowance.
- Required components covered Signature-Input must cover @authority or @target-uri, and the Signature-Agent header, which every signed request carries.
- Signature-Input parses The request must carry both a Signature and a Signature-Input header, and both must parse as RFC 9421 structured fields.
- Required parameters present The signature parameters must include created, expires, keyid, and tag.
- Web Bot Auth tag The tag parameter must be exactly web-bot-auth.
- keyid resolves to a key The signature's keyid must match a key in the directory by its computed RFC 7638 thumbprint.
- Replay and freshness Informational: passes with or without a nonce, because the protocol draft adds no nonce requirement. Replay protection rests on the validity window and on the verifier.
- Signature validity window The draft recommends an expiry no more than 24 hours after creation; a longer window raises an advisory warning, not a failure.
Agent card checks
- robots.txt (RFC 9309) compliance The Signature Agent Card should declare whether the agent honours robots.txt as defined in RFC 9309.
- Agent card discovery Whether a Signature Agent Card was found at all, and whether what was found is a Web Bot Auth card rather than an A2A or MCP one.
- Agent card client_id Advisory: when the Signature Agent Card carries a client_id, it must be the exact URL the card was fetched from.
- Agent card client name The Signature Agent Card should declare a client_name: a human-readable name for the operator behind the agent.
- Agent card client URI The Signature Agent Card should declare a client_uri: a URL that identifies the operator behind the agent.
- Agent card contacts The Signature Agent Card should declare contacts: one or more addresses for reaching the operator.
- Agent card key material The Signature Agent Card should point to its keys with an https jwks_uri or carry them inline as jwks, never both.
- Agent card purpose The Signature Agent Card should declare a purpose: a short statement of what the agent does.
- Rate expectation The Signature Agent Card should declare a rate expectation or rate control: how often the agent expects to request.