Directory endpoint reachable

What this check verifies

This check fetches the well-known directory path and confirms the endpoint answers with an HTTP 2xx status. The checker follows redirects for this fetch and grades the response at the end of the chain. It covers two failure shapes:

1. The endpoint cannot be reached at all: a connection failure, timeout, DNS error, or a malformed redirect. Nothing was served.
2. The endpoint answers, but with a non-2xx status such as 404, 403, or 500.

A 403 that carries cf-mitigated: challenge gets its own message: a bot-protection challenge blocked the checker, and it blocks verifiers that fetch your directory in the same way.

A 2xx response passes here. Whether it was a direct 200, which verifiers require, is reported separately by Directory served directly with 200.

Either case means there is no usable directory at that path. When nothing is served, this is the only directory check that runs; the media type, JSON, and per-key checks would be meaningless with no response to inspect.

Why it matters

A verifier that fetches your well-known path and gets a 404 has nothing to check a signature against, so your signed requests cannot be verified. The protocol draft requires status 200 and tells verifiers to treat every other status as a discovery failure (section 5.5). A 404 is the standard signal for “no directory published here,” which is different from a directory that exists but is broken.

For this reason the result feeds the report verdict rather than the letter grade. An unreachable or non-2xx endpoint is reported as NOT FOUND, and the grade is hidden, because a 404 with an HTML error body is not a low-grade directory; it is the absence of one. A grade is only meaningful once a directory is actually served.

How to fix it

1. Confirm the directory is served at exactly https://<your-host>/.well-known/http-message-signatures-directory and returns HTTP 200.
2. Check for a path typo, a route that only matches a trailing slash, or a host that resolves to the wrong origin.
3. If you return 403 or 401, remove the auth requirement: the directory is public data and must be fetchable without credentials.
4. If bot protection challenges the request, exempt the well-known path from it. The protocol draft asks operators to keep the directory reachable without Web Bot Auth on the directory request and to avoid bot protection rules that block verifier fetches (Appendix C.2).
5. Serve the directory without a redirect. Verifiers do not follow redirects (see Directory served directly with 200).

Common causes are a missing route for the well-known path, a reverse proxy that does not forward it, or an origin returning a 5xx error. Fetch the URL yourself and confirm the status line reads 200.

References

• The Web Bot Auth protocol draft (draft-ietf-webbotauth-httpsig-protocol-00) registers the well-known directory endpoint (section 8.1), requires status 200 (section 5.5), and covers directory availability (Appendix C.2).
• RFC 7517 defines the key-set document the endpoint returns.
• How grading works explains why an unreachable endpoint is treated as NOT FOUND rather than graded.