test: re-pin WWW-Authenticate assertions to the scope-bearing challenge

The interaction and docs_src suites pinned the old scope-less challenge
as a recorded divergence (hosting:auth:scope-403 and the scope half of
hosting:auth:missing-401 / invalid-401 / expired-401). Now that the
middleware emits the RFC 6750 scope attribute, follow the divergence
lifecycle: re-pin those tests to the spec-correct output, drop the
resolved Divergence records, keep the still-open no-credentials
error-code divergence on hosting:auth:missing-401, and refresh the
docstrings and docs page that described the old behaviour.

Author: claude

docs/run/authorization.md

@@ -68,7 +68,7 @@ This document is how a client that has never heard of your server finds its way
 
     ```text
     HTTP/1.1 401 Unauthorized
-    WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"
+    WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required", scope="notes:read", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"
 
     {"error": "invalid_token", "error_description": "Authentication required"}
     ```

tests/docs_src/test_authorization.py

@@ -62,7 +62,7 @@ async def test_a_request_without_a_token_never_reaches_the_protocol() -> None:
     assert response.status_code == 401
     assert response.json() == {"error": "invalid_token", "error_description": "Authentication required"}
     assert response.headers["www-authenticate"] == (
-        'Bearer error="invalid_token", error_description="Authentication required", '
+        'Bearer error="invalid_token", error_description="Authentication required", scope="notes:read", '
         'resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"'
     )
 

tests/interaction/_requirements.py

@@ -2859,18 +2859,12 @@ def __post_init__(self) -> None:
         behavior="An expired token returns 401 invalid_token.",
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; 401 is an HTTP status code.",
-        divergence=Divergence(
-            note="The challenge carries no `scope` parameter; see the note on hosting:auth:missing-401.",
-        ),
     ),
     "hosting:auth:invalid-401": Requirement(
         source=f"{SPEC_BASE_URL}/basic/authorization#token-handling",
         behavior="A malformed bearer token or token-verification failure returns 401 with WWW-Authenticate.",
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; 401 is an HTTP status code.",
-        divergence=Divergence(
-            note="The challenge carries no `scope` parameter; see the note on hosting:auth:missing-401.",
-        ),
     ),
     "hosting:auth:metadata-endpoints": Requirement(
         source=f"{SPEC_BASE_URL}/basic/authorization#authorization-server-location",
@@ -2892,11 +2886,8 @@ def __post_init__(self) -> None:
         note="Auth is enforced at the HTTP layer; 401 is an HTTP status code.",
         divergence=Divergence(
             note=(
-                "The SDK never emits a `scope` parameter in any WWW-Authenticate challenge — neither the "
-                "discovery-time 401 (#protected-resource-metadata-discovery-requirements SHOULD) nor the "
-                "runtime 403 (#runtime-insufficient-scope-errors SHOULD); and for the no-credentials case "
-                'it emits error="invalid_token", which RFC 6750 Section 3.1 says SHOULD NOT appear when no '
-                "authentication information was presented."
+                'For the no-credentials case the SDK emits error="invalid_token", which RFC 6750 '
+                "Section 3.1 says SHOULD NOT appear when no authentication information was presented."
             ),
         ),
     ),
@@ -2925,13 +2916,6 @@ def __post_init__(self) -> None:
         ),
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; 403 is an HTTP status code.",
-        divergence=Divergence(
-            note=(
-                'The SDK emits error="insufficient_scope" and error_description but never the `scope` '
-                "parameter the spec SHOULD include; the SDK client reads `scope` from this header to drive "
-                "step-up (utils.py extract_scope_from_www_auth) — a resource-server/client asymmetry."
-            ),
-        ),
     ),
     "hosting:auth:as:authorize-requires-pkce": Requirement(
         source=f"{SPEC_BASE_URL}/basic/authorization#authorization-code-protection",

tests/interaction/auth/_harness.py

@@ -312,9 +312,10 @@ def step_up_shim(www_authenticate: str, *, on_nth_authenticated_post: int = 2) -
     """Build an `app_shim` that 403s the Nth authenticated POST to `/mcp` with the given challenge.
 
     Subsequent requests pass through. Used to drive the client's `insufficient_scope` step-up
-    handling: the SDK's bearer middleware never emits `scope=` in its 403 challenge (see the
-    divergence on `hosting:auth:scope-403`), so the test supplies the 403 itself. Reserve this
-    pattern for behaviour the real server cannot be made to produce.
+    handling with a challenge shape the real bearer middleware cannot be made to produce for
+    the scenario under test (e.g. a `scope` differing from the configured `required_scopes`,
+    or a challenge on a request the middleware would let through). Reserve this pattern for
+    behaviour the real server cannot be made to produce.
 
     The default `on_nth_authenticated_post=2` targets the `notifications/initialized` POST: the
     first authenticated POST is the auth flow's retry of the original initialize request (yielded

tests/interaction/auth/test_authorize_token.py

@@ -328,12 +328,12 @@ async def test_the_registered_auth_method_is_used_regardless_of_as_metadata_adve
 async def test_scope_is_selected_from_the_www_authenticate_challenge_over_prm_metadata() -> None:
     """When the 401 challenge carries `scope=`, that value is requested instead of the PRM scopes.
 
-    The SDK's bearer middleware never emits `scope=` in WWW-Authenticate (see the divergence
-    on `hosting:auth:scope-403`), so the test supplies the first 401 itself via
-    `first_challenge_shim` and disables token verification so the post-auth retry succeeds
-    regardless of the granted scope. PRM advertises `["from-prm"]` (it mirrors
-    `required_scopes`); the challenge says `from-header`; the authorize URL must carry
-    `from-header`.
+    The bearer middleware's own challenge would carry the configured `required_scopes`, which
+    PRM `scopes_supported` mirrors — indistinguishable from the PRM fallback — so the test
+    supplies the first 401 itself via `first_challenge_shim` with a `scope` that differs from
+    PRM, and disables token verification so the post-auth retry succeeds regardless of the
+    granted scope. PRM advertises `["from-prm"]` (it mirrors `required_scopes`); the challenge
+    says `from-header`; the authorize URL must carry `from-header`.
     """
     recorded, on_request = record_requests()
     provider = InMemoryAuthorizationServerProvider(default_scopes=["from-header"])

tests/interaction/auth/test_bearer.py

@@ -81,22 +81,23 @@ async def test_a_request_with_no_authorization_header_is_challenged_with_resourc
     """No `Authorization` header → 401 with a `WWW-Authenticate` carrying `resource_metadata`.
 
     The snapshot pins current behaviour: the SDK collapses the no-header, unknown-token, and
-    expired-token cases into one challenge (`error="invalid_token"`, no `scope` parameter). The
-    spec says the discovery-time challenge SHOULD include `scope` and RFC 6750 says the
-    no-credentials case SHOULD NOT carry an error code; both gaps are recorded as the divergence
-    on this requirement. Asserting the dict equals an exact key set also pins that no parameter
-    appears twice.
+    expired-token cases into one challenge. The `scope` parameter carries the configured required
+    scopes (spec SHOULD, RFC 6750 section 3; #3103). RFC 6750 also says the no-credentials case
+    SHOULD NOT carry an error code; that remaining gap is recorded as the divergence on this
+    requirement. Asserting the dict equals an exact key set also pins that no parameter appears
+    twice.
     """
     response = await post_mcp(protected)
 
     assert response.status_code == 401
     assert response.headers["www-authenticate"] == snapshot(
-        'Bearer error="invalid_token", error_description="Authentication required", '
+        'Bearer error="invalid_token", error_description="Authentication required", scope="mcp:read", '
         'resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"'
     )
     assert parse_www_authenticate(response.headers["www-authenticate"]) == {
         "error": "invalid_token",
         "error_description": "Authentication required",
+        "scope": REQUIRED_SCOPE,
         "resource_metadata": RESOURCE_METADATA_URL,
     }
     assert response.json() == snapshot({"error": "invalid_token", "error_description": "Authentication required"})
@@ -106,15 +107,16 @@ async def test_a_request_with_no_authorization_header_is_challenged_with_resourc
 async def test_an_unrecognized_bearer_token_is_answered_401_invalid_token(protected: httpx2.AsyncClient) -> None:
     """A token the verifier does not recognize is answered 401 `invalid_token`.
 
-    The challenge is identical to the no-header case (the backend returns `None` for both); the
-    missing `scope` parameter is the recorded divergence on this requirement.
+    The challenge is identical to the no-header case (the backend returns `None` for both),
+    including the `scope` parameter carrying the configured required scopes (#3103).
     """
     response = await post_mcp(protected, bearer="tok-unknown")
 
     assert response.status_code == 401
     assert parse_www_authenticate(response.headers["www-authenticate"]) == {
         "error": "invalid_token",
         "error_description": "Authentication required",
+        "scope": REQUIRED_SCOPE,
         "resource_metadata": RESOURCE_METADATA_URL,
     }
 
@@ -124,8 +126,7 @@ async def test_an_expired_token_is_answered_401(protected: httpx2.AsyncClient) -
     """A token whose `expires_at` is in the past is answered 401 `invalid_token`.
 
     The expiry check is the bearer backend's, against the wall clock; the test seeds a concrete
-    past timestamp so no time mocking is involved. The missing `scope` parameter is the recorded
-    divergence on this requirement.
+    past timestamp so no time mocking is involved.
     """
     response = await post_mcp(protected, bearer="tok-expired")
 
@@ -134,26 +135,24 @@ async def test_an_expired_token_is_answered_401(protected: httpx2.AsyncClient) -
 
 
 @requirement("hosting:auth:scope-403")
-async def test_a_token_missing_a_required_scope_is_answered_403_insufficient_scope_without_a_scope_param(
+async def test_a_token_missing_a_required_scope_is_answered_403_insufficient_scope_with_a_scope_param(
     protected: httpx2.AsyncClient,
 ) -> None:
-    """A token lacking the required scope is answered 403 `insufficient_scope`, with no `scope` parameter.
+    """A token lacking the required scope is answered 403 `insufficient_scope` with a `scope` parameter.
 
-    The spec's runtime-insufficient-scope guidance says the challenge SHOULD include `scope`
-    naming the required scope; the SDK never emits it, recorded as the divergence on this
-    requirement. The SDK client reads `scope` from this header to drive step-up, so the gap is
-    a resource-server/client asymmetry.
+    The spec's runtime-insufficient-scope guidance (and RFC 6750 section 3.1) says the challenge
+    SHOULD include `scope` naming the required scope; the SDK client reads it from this header to
+    drive step-up authorization (#3103).
     """
     response = await post_mcp(protected, bearer="tok-noscope")
 
     assert response.status_code == 403
-    parsed = parse_www_authenticate(response.headers["www-authenticate"])
-    assert parsed == {
+    assert parse_www_authenticate(response.headers["www-authenticate"]) == {
         "error": "insufficient_scope",
         "error_description": f"Required scope: {REQUIRED_SCOPE}",
+        "scope": REQUIRED_SCOPE,
         "resource_metadata": RESOURCE_METADATA_URL,
     }
-    assert "scope" not in parsed
 
 
 @requirement("hosting:auth:aud-validation")