linkcheck builder: optionally allow HTTP 401 status code hyperlinks to be reported broken

CHANGES.rst

@@ -304,6 +304,8 @@ Features added
 
 Bugs fixed
 ----------
+* #11433: The ``linkcheck`` builder has been updated to consider hyperlinks
+  that respond with an HTTP 401 (unauthorized) response to be broken.
 
 * Restored the ``footnote-reference`` class that has been removed in
   the latest (unreleased) version of Docutils.

sphinx/builders/linkcheck.py

@@ -437,9 +437,8 @@ def _check_uri(self, uri: str, hyperlink: Hyperlink) -> tuple[str, str, int]:
             except HTTPError as err:
                 error_message = str(err)
 
-                # Unauthorised: the reference probably exists
                 if status_code == 401:
-                    return 'working', 'unauthorized', 0
+                    return 'broken', 'unauthorized', 0
 
                 # Rate limiting; back-off if allowed, or report failure otherwise
                 if status_code == 429:

tests/test_build_linkcheck.py

@@ -343,8 +343,12 @@ class CustomHandler(http.server.BaseHTTPRequestHandler):
 
         def authenticated(method):
             def method_if_authenticated(self):
-                if (expected_token is None
-                        or self.headers["Authorization"] == f"Basic {expected_token}"):
+                if expected_token is None:
+                    return method(self)
+                elif not self.headers["Authorization"]:
+                    self.send_response(401, "Unauthorized")
+                    self.end_headers()
+                elif self.headers["Authorization"] == f"Basic {expected_token}":
                     return method(self)
                 else:
                     self.send_response(403, "Forbidden")
@@ -397,9 +401,7 @@ def test_auth_header_no_match(app):
     with open(app.outdir / "output.json", encoding="utf-8") as fp:
         content = json.load(fp)
 
-    # TODO: should this test's webserver return HTTP 401 here?
-    # https://github.com/sphinx-doc/sphinx/issues/11433
-    assert content["info"] == "403 Client Error: Forbidden for url: http://localhost:7777/"
+    assert content["info"] == "unauthorized"
     assert content["status"] == "broken"