Signature-Agent header

What this check verifies

A Web Bot Auth request carries a Signature and a Signature-Input header, and usually a Signature-Agent header that names the directory holding the signing key. The value is an RFC 8941 structured field: a quoted string item holding the directory URL, for example "https://example.com".

This check looks for the header and confirms it is a well-formed structured field. When the header is present it passes. When it is absent the check is advisory, a warning rather than a failure, because the architecture draft only requires signature-agent to be covered by the signature when the header is sent at all.

The header has a second effect. If you send it, signature-agent becomes a required covered component, checked under Required components covered.

Why it matters

Signature-Agent tells a verifier where to fetch your public keys. Without it, a verifier has to already know which directory belongs to your agent, which only works for agents it has seen before. With it, any verifier can resolve keyid against the named directory and check the signature with no prior arrangement.

If the header is present but malformed (an unquoted value, or something that is not a valid structured field), a strict verifier may reject it or read the wrong value, and the request fails to verify even when the key and signature are otherwise fine.

How to fix it

1. Send the header as a structured-field string item, with the directory URL in quotes:

Signature-Agent: "https://example.com"

2. Use an HTTPS URL that hosts the directory at the well-known path, the same origin a verifier will fetch to resolve keyid.
3. If you send Signature-Agent, also list signature-agent in the covered components of Signature-Input. Sending the header but leaving it uncovered is a covered-components failure.

If your agent does not send the header at all, that is allowed. This check only warns, and the rest of the signature can still verify against a directory the verifier already knows.

References

• RFC 9421 defines HTTP Message Signatures, including the Signature and Signature-Input headers.
• RFC 8941 defines structured field values, including string items.
• The web-bot-auth architecture draft makes signature-agent a required covered component only when the header is sent.
• How grading works explains how advisory checks affect the score.