Address review: split the auth-method usability sets, seal the parse boundary

Two conflated questions shared one recognized-method set: whether the
authorization-code registration flow can act on an assigned method, and
whether a stored record may carry a method without the token step
erroring. The flow authenticates with the minted secret and holds no key
to sign a private_key_jwt assertion, so it now rejects that method at
registration too, while prepare_token_auth still tolerates it for
PrivateKeyJWTOAuthProvider's inherited refresh path.

An explicit JSON null in the registration response is now read as an
omitted key across the whole record, so grant_types and response_types
(which pydantic rejects null for) parse like the other fields. The
SDK-internal issuer binding is cleared after parsing, so a body echoing
an "issuer" member cannot seed it. The bundled registration endpoint
sets client_secret_expires_at to 0 rather than omitting it whenever a
client_secret is issued with no expiry configured, as RFC 7591 3.2.1
requires. The migration entry now names both exception surfaces.

Author: maxisbey

docs/migration.md

@@ -2196,7 +2196,7 @@ class OAuthClientInformationFull(OAuthClientMetadataBase): ...   # server record
 
 On `OAuthClientInformationFull`, `application_type` and `token_endpoint_auth_method` are now `str | None`, `grant_types` is `list[str]`, and `redirect_uris` is optional (`list[AnyUrl] | None`, no minimum length). `client_id` is now required (`str`): [RFC 7591 §3.2.1](https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1) makes it mandatory in the response, and a record of a registered client without one was never meaningful. Code that only reads these fields is unaffected. Code that relied on `isinstance(client_info, OAuthClientMetadata)`, or passed an `OAuthClientInformationFull` where an `OAuthClientMetadata` is expected, must reference the record type directly. `validate_scope()` and `validate_redirect_uri()` moved with the record: they are methods of `OAuthClientInformationFull` (the type authorization-server code holds) and are no longer available on `OAuthClientMetadata`.
 
-A registration response the server sends is no longer rejected on these fields (an echoed `""` for `token_endpoint_auth_method` or `application_type` is treated as absent, as it already was for the optional URL fields). Whether a substituted value is usable is decided where the value is used: a registered `token_endpoint_auth_method` this SDK does not recognize (anything other than `none`, `client_secret_post`, `client_secret_basic`, or `private_key_jwt`) now raises `OAuthTokenError` naming the method at the token exchange, rather than the token request being sent unauthenticated for the server to reject.
+A registration response the server sends is no longer rejected on these fields: an echoed `""` for `token_endpoint_auth_method` or `application_type` reads as absent (as it already did for the optional URL fields), and a member serialized as an explicit `null` reads as an omitted key, so its default applies. Whether a substituted value is usable is judged where it matters, not at parse. When Dynamic Client Registration completes with a `token_endpoint_auth_method` the authorization-code flow cannot apply - anything other than `none`, `client_secret_post`, or `client_secret_basic`, including `private_key_jwt`, whose assertion that flow has no key to sign - the client raises `OAuthRegistrationError` naming the method, before the record is stored or authorization begins. Separately, a stored or pre-registered record carrying a method the SDK does not know at all raises `OAuthTokenError` when it reaches the token exchange (`private_key_jwt` on such a record is fine: `PrivateKeyJWTOAuthProvider` supplies the assertion, and its refresh path still works).
 
 The SDK's own registration endpoint also now returns all registered metadata in its 201 response (RFC 7591 §3.2.1), including the client's `application_type`, which v1 dropped from the echo (silently reporting the default in place of a client's `"web"`).
 

src/mcp/client/auth/oauth2.py

@@ -59,28 +59,38 @@
 
 logger = logging.getLogger(__name__)
 
-# Methods `OAuthContext.prepare_token_auth` recognizes on a registered client, derived from the
-# same set the SDK is willing to request so the two cannot drift. `None`/"none" send no client
-# secret; `private_key_jwt` adds no secret here (its assertion is supplied by
-# `PrivateKeyJWTOAuthProvider`). Anything else is a method this client cannot apply.
-_RECOGNIZED_TOKEN_ENDPOINT_AUTH_METHODS: tuple[str | None, ...] = (None, *get_args(TokenEndpointAuthMethod))
+# Methods a registered client's record may carry without a token request being an error,
+# derived from the set the SDK is willing to request so the two cannot drift. `None`/"none"
+# send no client secret; `private_key_jwt` sends none from here either, its assertion being
+# added by `PrivateKeyJWTOAuthProvider` (whose inherited refresh path passes through
+# `prepare_token_auth`). Anything else is a method no client here can apply.
+_KNOWN_TOKEN_ENDPOINT_AUTH_METHODS: tuple[str | None, ...] = (None, *get_args(TokenEndpointAuthMethod))
+
+# Methods a registration completed by the authorization-code flow can act on. That flow
+# authenticates the token request with the minted client secret (or nothing); it holds no key
+# to sign a `private_key_jwt` assertion, so a server assigning that method has registered a
+# client this flow cannot use. `PrivateKeyJWTOAuthProvider` never registers dynamically.
+_REGISTRATION_USABLE_TOKEN_ENDPOINT_AUTH_METHODS: tuple[str | None, ...] = tuple(
+    method for method in _KNOWN_TOKEN_ENDPOINT_AUTH_METHODS if method != "private_key_jwt"
+)
 
 
 def check_registration_usable(client_info: OAuthClientInformationFull) -> None:
-    """Confirm a completed registration is one this client can act on.
+    """Confirm a registration this flow completed is one it can act on.
 
     RFC 7591 §3.2.1 lets the authorization server replace requested metadata and leaves it to
     the client to "check the values in the response to determine if the registration is
     sufficient for use". The one substitution that makes the minted credentials unusable is a
-    token-endpoint auth method this client cannot apply, so it is judged here - before the
-    record is persisted or any interactive authorization begins - rather than surfacing later
-    as an opaque failure at the token endpoint.
+    token-endpoint auth method the authorization-code flow cannot apply - one it does not
+    implement, or `private_key_jwt`, whose assertion this flow has no key to sign - so it is
+    judged here, before the record is persisted or any interactive authorization begins,
+    rather than surfacing later as an opaque failure at the token endpoint.
 
     Raises:
         OAuthRegistrationError: The server registered the client with a
-            `token_endpoint_auth_method` this client does not implement.
+            `token_endpoint_auth_method` this flow cannot apply.
     """
-    if client_info.token_endpoint_auth_method not in _RECOGNIZED_TOKEN_ENDPOINT_AUTH_METHODS:
+    if client_info.token_endpoint_auth_method not in _REGISTRATION_USABLE_TOKEN_ENDPOINT_AUTH_METHODS:
         raise OAuthRegistrationError(
             "Authorization server registered the client with unsupported token_endpoint_auth_method "
             f"{client_info.token_endpoint_auth_method!r}"
@@ -246,7 +256,7 @@ def prepare_token_auth(
             # Include client_id and client_secret in request body (RFC 6749 §2.3.1)
             data["client_id"] = self.client_info.client_id
             data["client_secret"] = self.client_info.client_secret
-        elif auth_method not in _RECOGNIZED_TOKEN_ENDPOINT_AUTH_METHODS:
+        elif auth_method not in _KNOWN_TOKEN_ENDPOINT_AUTH_METHODS:
             raise OAuthTokenError(f"Registered client uses unsupported token_endpoint_auth_method {auth_method!r}")
         # For "none" (or absent), don't add any client_secret; "private_key_jwt" adds its
         # assertion in the provider that implements it, not here.

src/mcp/client/auth/utils.py

@@ -300,9 +300,13 @@ async def handle_registration_response(response: Response) -> OAuthClientInforma
     try:
         content = await response.aread()
         client_info = OAuthClientInformationFull.model_validate_json(content)
-        return client_info
     except ValidationError as e:
         raise OAuthRegistrationError(f"Invalid registration response: {e}") from e
+    # `issuer` is the SDK's own binding of these credentials to the server they were
+    # registered with (SEP-2352), stamped by the auth flow - never taken from the wire.
+    # A body echoing an "issuer" member must not seed the trust binding.
+    client_info.issuer = None
+    return client_info
 
 
 def is_valid_client_metadata_url(url: str | None) -> bool:

src/mcp/server/auth/handlers/register.py

@@ -106,11 +106,15 @@ async def handle(self, request: Request) -> Response:
             )
 
         client_id_issued_at = int(time.time())
-        client_secret_expires_at = (
-            client_id_issued_at + self.options.client_secret_expiry_seconds
-            if self.options.client_secret_expiry_seconds is not None
-            else None
-        )
+        # RFC 7591 §3.2.1: client_secret_expires_at is REQUIRED whenever a client_secret is
+        # issued, with 0 (not omission) meaning it never expires; a public client gets none.
+        client_secret_expires_at = None
+        if client_secret is not None:
+            client_secret_expires_at = (
+                client_id_issued_at + self.options.client_secret_expiry_seconds
+                if self.options.client_secret_expiry_seconds is not None
+                else 0
+            )
 
         # RFC 7591 §3.2.1: the response returns all registered metadata about the client, so
         # the record is the whole validated request plus the credentials minted here - built

src/mcp/shared/auth.py

@@ -1,6 +1,6 @@
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
-from pydantic import AnyHttpUrl, AnyUrl, BaseModel, ConfigDict, Field, field_validator
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, ConfigDict, Field, field_validator, model_validator
 
 # RFC 7523 JWT bearer grant; SEP-990 leg 2 uses this to present the ID-JAG.
 JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer"
@@ -136,9 +136,11 @@ class OAuthClientInformationFull(OAuthClientMetadataBase):
     requested metadata values submitted during the registration and substitute them with
     suitable values", so `application_type`, `token_endpoint_auth_method`, and `grant_types`
     are typed to accept any string the server echoes, and `redirect_uris` may be absent or
-    empty. Whether a substituted value is usable is decided where the value is used, not at
-    parse. `redirect_uris` elements are still parsed as URLs, as the authorization server
-    compares them against a client's requested `redirect_uri`.
+    empty. A member the server serializes as an explicit `null` is read as omitted, so the
+    field's default applies rather than the parse failing. Whether a substituted value is
+    usable is decided where the value is used, not at parse. `redirect_uris` elements are
+    still parsed as URLs, as the authorization server compares them against a client's
+    requested `redirect_uri`.
     """
 
     redirect_uris: list[AnyUrl] | None = None
@@ -160,6 +162,17 @@ class OAuthClientInformationFull(OAuthClientMetadataBase):
     # RFC 7591 field) to detect authorization-server migration and avoid cross-AS credential reuse.
     issuer: str | None = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def _explicit_null_reads_as_omitted(cls, data: object) -> object:
+        # Servers that serialize their client record dump unset members as null instead of
+        # omitting the keys; a null for a list field would otherwise fail the parse (and
+        # discard an already-provisioned registration). null and absent mean the same thing.
+        if isinstance(data, dict):
+            members = cast(dict[str, Any], data)
+            return {key: value for key, value in members.items() if value is not None}
+        return data
+
     @field_validator("token_endpoint_auth_method", "application_type", mode="before")
     @classmethod
     def _empty_string_optional_metadata_to_none(cls, v: object) -> object:

tests/client/test_auth.py

@@ -1030,6 +1030,19 @@ async def test_registration_response_with_substituted_metadata_yields_the_creden
     assert client_info.application_type == "confidential"
 
 
+@pytest.mark.anyio
+async def test_registration_response_does_not_seed_the_issuer_binding_from_the_body():
+    """The issuer binding (SEP-2352) is the SDK's record of which server it registered with,
+    stamped by the auth flow; an "issuer" member in the untrusted response body must not
+    populate it, or a mismatched binding would discard the credentials on every 401."""
+    body = b'{"client_id": "issued-id", "issuer": "https://not-the-flow.example"}'
+
+    client_info = await handle_registration_response(httpx2.Response(201, content=body))
+
+    assert client_info.client_id == "issued-id"
+    assert client_info.issuer is None
+
+
 @pytest.mark.anyio
 async def test_a_2xx_body_that_is_not_client_information_is_an_oauth_registration_error():
     """A success status whose body is not client information surfaces as OAuthRegistrationError."""

tests/interaction/_requirements.py

@@ -2944,8 +2944,9 @@ def __post_init__(self) -> None:
         source="sdk",
         behavior=(
             "The bundled registration endpoint returns all registered metadata about the client "
-            "in its 201 response (RFC 7591 §3.2.1), including the client's `application_type` "
-            "rather than a substituted default."
+            "in its 201 response (RFC 7591 §3.2.1) - the client's `application_type` rather than a "
+            "substituted default, and `client_secret_expires_at` (0 when the secret never expires) "
+            "whenever a `client_secret` is issued."
         ),
         transports=("streamable-http",),
         note="Auth is enforced at the HTTP layer; the bundled AS is an ASGI app.",
@@ -3675,8 +3676,9 @@ def __post_init__(self) -> None:
         behavior=(
             "A 201 registration response whose echoed metadata the server substituted (RFC 7591 §3.2.1) - "
             "an unregistered application_type, null redirect_uris, extra grant types - completes the flow; "
-            "a substituted token_endpoint_auth_method the client cannot apply is instead reported as an "
-            "OAuthRegistrationError before the record is persisted or authorization begins."
+            "a substituted token_endpoint_auth_method the authorization-code flow cannot apply (an "
+            "unimplemented method, or private_key_jwt, whose assertion it has no key to sign) is instead "
+            "reported as an OAuthRegistrationError before the record is persisted or authorization begins."
         ),
         transports=("streamable-http",),
         note="OAuth is HTTP-only.",

tests/interaction/auth/test_as_handlers.py

@@ -258,8 +258,12 @@ async def test_registration_response_echoes_the_registered_application_type(
     response = await http.post("/register", json=body | {"application_type": application_type})
 
     assert response.status_code == 201
-    info = OAuthClientInformationFull.model_validate_json(response.content)
-    assert info.application_type == application_type
+    echoed = response.json()
+    assert echoed["application_type"] == application_type
+    # A secret was issued and no expiry is configured, so RFC 7591 §3.2.1 requires the
+    # response to carry client_secret_expires_at, with 0 (present, not omitted) for "never".
+    assert echoed["client_secret"]
+    assert echoed["client_secret_expires_at"] == 0
 
 
 @requirement("hosting:auth:as:redirect-uri-binding")

tests/interaction/auth/test_discovery.py

@@ -223,18 +223,23 @@ async def test_a_registration_response_with_substituted_metadata_completes_the_f
 
 
 @requirement("client-auth:dcr:substituted-metadata")
-async def test_a_registration_assigning_an_unusable_auth_method_surfaces_as_a_registration_error() -> None:
-    """A 201 assigning an auth method the client cannot apply is a registration error.
+@pytest.mark.parametrize("auth_method", ["client_secret_jwt", "private_key_jwt"])
+async def test_a_registration_assigning_an_unusable_auth_method_surfaces_as_a_registration_error(
+    auth_method: str,
+) -> None:
+    """A 201 assigning an auth method this flow cannot apply is a registration error.
 
     RFC 7591 §3.2.1 leaves it to the client to judge whether a substituted value makes the
-    registration usable; an unimplemented token-endpoint auth method does not, and is
-    reported before the record is stored or any authorize/token request is made.
+    registration usable. The authorization-code flow authenticates with the minted secret, so
+    neither an unimplemented method nor `private_key_jwt` (an assertion it has no key to
+    sign) is usable; both are reported before the record is stored or any authorize/token
+    request is made.
     """
     recorded, on_request = record_requests()
     provider = InMemoryAuthorizationServerProvider()
     server = Server("guarded", on_list_tools=list_tools)
     body = json.dumps(
-        {"client_id": "jwt-only", "client_secret": "s3cr3t", "token_endpoint_auth_method": "client_secret_jwt"}
+        {"client_id": "unusable", "client_secret": "s3cr3t", "token_endpoint_auth_method": auth_method}
     ).encode()
     app_shim = shim(serve={"/register": (201, body)})
     storage = InMemoryTokenStorage()

tests/shared/test_auth.py

@@ -176,6 +176,25 @@ def test_a_registration_response_without_a_client_id_is_rejected():
         OAuthClientInformationFull.model_validate({"application_type": "web"})
 
 
+@pytest.mark.parametrize(
+    "nulled",
+    ["grant_types", "response_types", "redirect_uris", "application_type", "token_endpoint_auth_method", "scope"],
+)
+def test_client_information_reads_an_explicit_null_as_an_omitted_key(nulled: str):
+    """A server that dumps unset members as null (rather than omitting them) still yields a
+    usable registration: null and absent mean the same, so the field's default applies."""
+    info = OAuthClientInformationFull.model_validate({"client_id": "abc123", nulled: None})
+    defaults = OAuthClientInformationFull.model_validate({"client_id": "abc123"})
+    assert getattr(info, nulled) == getattr(defaults, nulled)
+
+
+def test_client_information_that_is_not_an_object_still_fails_the_parse():
+    """The null-as-omitted coercion only touches JSON objects; a body that is not one is
+    passed through and rejected as a normal validation failure rather than swallowed."""
+    with pytest.raises(ValidationError):
+        OAuthClientInformationFull.model_validate("not-an-object")
+
+
 @pytest.mark.parametrize("empty_field", ["token_endpoint_auth_method", "application_type"])
 def test_client_information_empty_string_metadata_coerced_to_absent(empty_field: str):
     """An echoed "" reads as absent, matching the URL-field coercion, so it is neither