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.
- Key validity window Optional nbf and exp on a key must be coherent: not already expired, 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 The checker computes each key's RFC 7638 thumbprint and reports it; a custom kid is allowed and never fails.
- 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, 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.
- Directory served over HTTPS The spec says the directory SHOULD use HTTPS; this checker treats plaintext HTTP as a hard failure with a grade cap, as deliberate policy.
Signature checks
- Signature-Agent header A Signature-Agent header points verifiers at the directory that holds your keys; it should be present and a well-formed structured-field dictionary.
- 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 signature-agent too whenever a Signature-Agent header is sent.
- 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 Advisory: passes when the draft-recommended nonce is present, warns when it is absent. Nonce uniqueness stays operator policy.
- 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 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 jwks_uri The Signature Agent Card should declare a jwks_uri: a URL to the JSON Web Key Set the agent signs with.
- 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.