Knowledge Base
Reference articles explaining how the checker works, what the grades mean, and what Web Bot Auth is.
Articles
- How grading works The 3-state verdict (VALID / INVALID / NOT FOUND), letter grades A-F, weighted scoring, and capping rules.
- 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.
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 Every key in the directory must use the Ed25519 curve (crv).
- Key type is OKP Every key in the directory must have key type (kty) OKP, the type used for Ed25519.
- 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 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 directory URL must use the HTTPS scheme; a plaintext HTTP URL fails.
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.
- 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, 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 An advisory note that replay protection is operator policy, not a hard protocol requirement. It never fails.
- Signature validity window A validity window longer than about an hour 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.