mcp 1.5.1 → 1.6.1

data/lib/mcp/client/oauth/flow.rb

@@ -14,7 +14,38 @@ module MCP
       # `Provider`; this class consumes a Provider plus signal data extracted from
       # the failing response (resource_metadata URL, scope challenge).
       class Flow
-        class AuthorizationError < StandardError; end
+        TOKEN_ENDPOINT_ERROR_MAX_LENGTH = 128
+        TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH = 512
+        METADATA_DIAGNOSTIC_MAX_LENGTH = 128
+        METADATA_URL_MAX_LENGTH = 2048
+
+        # Token request parameters the flow sets itself. Its values win over a provider's `token_request_params`,
+        # so a provider naming one of these is refused rather than left believing its value was sent.
+        RESERVED_TOKEN_REQUEST_PARAMS = [
+          "grant_type",
+          "client_id",
+          "client_secret",
+          "client_assertion",
+          "client_assertion_type",
+          "scope",
+          "resource",
+          "code",
+          "code_verifier",
+          "redirect_uri",
+          "refresh_token",
+          "assertion",
+        ].freeze
+
+        class AuthorizationError < StandardError
+          attr_reader :http_status, :error, :error_description
+
+          def initialize(message = nil, http_status: nil, error: nil, error_description: nil)
+            super(message)
+            @http_status = http_status
+            @error = error
+            @error_description = error_description
+          end
+        end
 
         # Raised specifically when the token endpoint rejects a grant with
         # `error: "invalid_grant"` (RFC 6749 §5.2). Callers use this to
@@ -28,6 +59,136 @@ module MCP
         # or authorization server metadata failure by rescuing a class rather than by matching the message text.
         class AuthorizationRefusedError < AuthorizationError; end
 
+        # Raised by metadata discovery when every candidate URL answered that nothing usable is published there
+        # (a `4xx` other than `429`, a redirect that was not followed, or a body that is not a JSON object).
+        # The only discovery failure that may select the legacy 2025-03-26 path.
+        class MetadataNotPublishedError < AuthorizationError; end
+
+        # Raised by metadata discovery when the answer says nothing about what is published: the request failed to
+        # reach the server, or a candidate answered `5xx` or `429`. Falling back on this would move
+        # the flow to a different authorization server because of a transient failure, so it is surfaced instead,
+        # as the TypeScript SDK does for network errors outside browsers and the Python SDK does for both.
+        class MetadataUnreachableError < AuthorizationError; end
+
+        # Raised for a `token_request_params` value the SDK refuses: a reserved key, a Hash comparing keys by identity,
+        # or anything but a Hash of Strings. An `ArgumentError` because the value is a configuration mistake,
+        # not a failed authorization, and deliberately outside `AuthorizationError`, which `MCP::Client::HTTP` treats on
+        # a failed refresh as a reason to run the interactive flow.
+        class InvalidTokenRequestParamsError < ArgumentError; end
+
+        # Raised by `RequestedOriginGuard` when middleware added through the provider's `http_client_customizer`
+        # would send a request to an origin other than the one the flow validated, or has dropped the record of
+        # the URL the flow asked for. An `ArgumentError` because the middleware is a configuration mistake,
+        # and deliberately outside `AuthorizationError`, which discovery treats as "nothing published"
+        # and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
+        class DestinationMismatchError < ArgumentError; end
+
+        # Faraday middleware registered on the connection `build_http_client` assembles before the customizer
+        # is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
+        # as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
+        # The guard covers what happens to a request after that record; middleware inserted ahead of it with
+        # `builder.insert(0, ...)` that rewrites the URL before it or rebuilds the environment is outside the guard.
+        # The record lives on the environment, not in `env.request.context`: that slot belongs to the application,
+        # which may fill it on the connection or replace it from a middleware of its own. Only the first URL seen
+        # on an environment is recorded: a middleware inserted ahead of this one that re-enters the stack after
+        # a `3xx` with the same environment, or with its `dup`, which shares the record, cannot replace it with
+        # the redirected URL.
+        class RequestedURLStamp
+          KEY = :mcp_oauth_requested_url
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(env)
+            env[KEY] ||= env.url.to_s
+            @app.call(env)
+          end
+        end
+
+        # Faraday middleware registered last on that connection, so it sees `env.url` after any customizer-added
+        # middleware has rewritten it or followed a redirect. A request that would leave the origin the flow asked
+        # for is refused before it reaches the adapter, since every destination check ran against the URL as
+        # written; a same-origin change stays with the server those checks admitted. The record survives
+        # the `env.dup` that redirect-following middleware performs, and a request that arrives without it is
+        # refused as well, so a middleware that rebuilds the environment fails closed rather than open.
+        # The origin boundary resembles the one the Python SDK keeps for its own auth requests, which follows
+        # a redirect itself only within the origin; this flow follows none.
+        class RequestedOriginGuard
+          def initialize(app)
+            @app = app
+          end
+
+          def call(env)
+            requested = env[RequestedURLStamp::KEY]
+            unless requested
+              raise DestinationMismatchError, <<~MESSAGE
+                Request to #{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect} carries no record of \
+                the URL the flow asked for; middleware that rebuilds the request environment is refused.
+              MESSAGE
+            end
+
+            unless Discovery.same_origin?(env.url.to_s, requested)
+              raise DestinationMismatchError, <<~MESSAGE
+                Request to #{Discovery.canonicalize_origin_and_path(requested).inspect} would be sent to \
+                #{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect}, on a different origin; \
+                middleware that follows redirects or rewrites URLs is refused.
+              MESSAGE
+            end
+
+            @app.call(env)
+          end
+        end
+        private_constant :RequestedURLStamp, :RequestedOriginGuard
+
+        class << self
+          # Returns why `params` cannot ride a token request as `token_request_params`, or `nil` when it can.
+          # Shared by the provider constructors and the flow, which both refuse the value with `InvalidTokenRequestParamsError`,
+          # so the same problem reads the same wherever it surfaces.
+          def token_request_params_problem(params)
+            return "must be a Hash (got #{params.class})." unless params.is_a?(Hash)
+
+            # Two equal keys are two entries here, which would be sent twice from a provider method
+            # or silently collapse into one when the constructors copy the Hash.
+            return "must not compare keys by identity." if params.compare_by_identity?
+
+            params.each do |key, value|
+              return "keys must be Strings (got #{key.class})." unless key.is_a?(String)
+              return "values must be Strings (got #{value.class} for #{key.inspect})." unless value.is_a?(String)
+              return "must not set #{key.inspect}, which the SDK sets itself." if RESERVED_TOKEN_REQUEST_PARAMS.include?(key)
+            end
+
+            nil
+          end
+
+          # Builds the connection the flow uses for its own requests: the SDK's defaults, `RequestedURLStamp`,
+          # then `customizer` (a provider's `http_client_customizer`, called with the `Faraday::Connection`),
+          # then `RequestedOriginGuard` last so it sees what the customizer's middleware does to each request
+          # after the stamp recorded it. Every request on the connection passes through both, so a caller using
+          # it directly is held to the same origin rule.
+          #
+          # Deliberately built without redirect-following middleware. Every destination check in this class runs
+          # against the URL as written, before the request goes out, so a connection that transparently followed
+          # a `3xx` would let a server reach a host the checks just refused. The guard turns following at
+          # the middleware level into a refusal; following inside an adapter stays invisible, so a customizer must
+          # not enable it.
+          #
+          # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
+          # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
+          # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
+          # after the check.
+          def build_http_client(customizer = nil)
+            require "faraday"
+
+            Faraday.new do |faraday|
+              faraday.headers["Accept"] = "application/json"
+              faraday.use(RequestedURLStamp)
+              customizer&.call(faraday)
+              faraday.use(RequestedOriginGuard)
+            end
+          end
+        end
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
@@ -75,7 +236,7 @@ module MCP
 
           ensure_pkce_supported!(as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm || {})
+          effective_scope = resolve_scope(scope: scope, prm: prm)
           effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
 
           # Asked before registering, not after: a refusal must not leave this client registered at an authorization server
@@ -126,7 +287,7 @@ module MCP
         # Runs the OAuth 2.1 `client_credentials` grant (machine-to-machine, no user interaction) and persists
         # the resulting token. Shares the same discovery and security checks as `run!`; the only difference is
         # the grant exchanged at the token endpoint. There is no PKCE, redirect, or authorization request,
-        # and no `offline_access` augmentation because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3).
+        # and no `offline_access` augmentation because the grant is not expected to issue a refresh token (OAuth 2.1 Section 4.3.3).
         # The pre-registered `client_id` / `client_secret` come from the provider's stored `client_information`.
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
         def run_client_credentials!(as_metadata:, prm:, resource:, scope:, server_url:)
@@ -219,19 +380,22 @@ module MCP
         # checks before talking to it.
         #
         # Returns `:refreshed` on success. Raises `AuthorizationError` when the provider has no refresh token, no client information,
+        # when a `client_credentials` or `jwt-bearer` provider's tokens record no issuer,
         # or when the token endpoint refuses the refresh request.
         # https://www.rfc-editor.org/rfc/rfc6749#section-6
         def refresh!(server_url:, resource_metadata_url: nil)
           refresh_token = read_token("refresh_token")
           raise AuthorizationError, "Cannot refresh: no refresh_token in provider storage." unless refresh_token
 
+          ensure_refresh_token_issuer_recorded!
+
           stored_client_info = @provider.client_information
           have_stored_client_info = stored_client_info.is_a?(Hash) && client_info_required_value(stored_client_info, "client_id")
 
           # A CIMD-configured provider stores no `client_information` on purpose
           # (the CIMD URL is re-resolved against the live AS metadata on every flow).
           # Allow refresh to proceed in that case so the `refresh_token` obtained via the CIMD flow remains usable.
-          have_cimd_url = !@provider.client_id_metadata_document_url.nil?
+          have_cimd_url = !provider_client_id_metadata_document_url.nil?
 
           unless have_stored_client_info || have_cimd_url
             raise AuthorizationError, "Cannot refresh: no client_information in provider storage."
@@ -267,7 +431,7 @@ module MCP
             ensure_refreshable_client_information!(stored_client_info, as_metadata: as_metadata)
             stored_client_info
           elsif as_metadata["client_id_metadata_document_supported"] == true
-            { "client_id" => @provider.client_id_metadata_document_url }
+            { "client_id" => provider_client_id_metadata_document_url }
           else
             raise AuthorizationError,
               "Cannot refresh: provider has a CIMD URL but the authorization server no longer advertises " \
@@ -319,7 +483,12 @@ module MCP
         #
         # Legacy path (2025-03-26 backwards compatibility): when the server publishes no PRM, `prm` is nil
         # and the MCP server's own origin acts as the authorization base URL, matching the TypeScript and Python SDKs.
-        # Any PRM discovery failure (404s, network errors, malformed documents) selects the legacy path, mirroring both SDKs' behavior.
+        # Only a discovery answer saying that nothing usable is published (`MetadataNotPublishedError`: a `4xx` other than `429`,
+        # a redirect that was not followed, or a body that is not a JSON object) selects the legacy path.
+        # A request that failed to reach the server, or returned a `5xx` or `429`, says nothing about what the server publishes,
+        # so once no candidate has served a usable document it is surfaced instead (`MetadataUnreachableError`),
+        # as both SDKs do for network errors (the TypeScript SDK outside browsers) and the Python SDK does for server errors.
+        # A body over the response cap is refused outright and never reaches the fallback either.
         # https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery
         def locate_authorization_server(server_url:, resource_metadata_url:)
           prm = begin
@@ -327,7 +496,7 @@ module MCP
               server_url: server_url,
               resource_metadata_url: resource_metadata_url,
             )
-          rescue AuthorizationError
+          rescue MetadataNotPublishedError
             nil
           end
 
@@ -349,16 +518,26 @@ module MCP
 
         # Fetches and validates the authorization server's RFC 8414 metadata.
         #
-        # On the modern path the metadata `issuer` must be byte-identical to the discovery URL (RFC 8414 Section 3.3).
-        # On the legacy 2025-03-26 path that validation is skipped: the legacy spec predates the requirement,
-        # and a pre-PRM server may host its OAuth endpoints under a path prefix whose `issuer` legitimately differs from
-        # the origin the metadata was discovered at (neither the TypeScript nor the Python SDK validates the issuer on this path).
+        # The metadata `issuer` must be byte-identical to the discovery URL (RFC 8414 Section 3.3) on both paths.
+        # On the legacy 2025-03-26 path the discovery URL is the MCP server's origin, which that spec names as
+        # the authorization base URL and which a document may render with a trailing slash; the TypeScript and Python SDKs
+        # accept the same slash-only difference. A document naming any other issuer is refused: an unverified `issuer`
+        # would otherwise become the identity tokens and client information are bound to, assertions are minted for,
+        # and the validator is shown, so a server could claim another authorization server and unlock the credentials
+        # bound to it.
         # When even the metadata document is absent, the legacy spec's default endpoints are used.
         def authorization_server_metadata(authorization_server:, legacy:, server_url:)
           metadata = if legacy
-            begin
+            fetched = begin
               fetch_authorization_server_metadata(issuer_url: authorization_server)
             rescue AuthorizationError
+              nil
+            end
+
+            if fetched
+              ensure_legacy_issuer_matches!(expected: authorization_server, returned: fetched["issuer"])
+              fetched
+            else
               default_legacy_metadata(authorization_server)
             end
           else
@@ -403,6 +582,14 @@ module MCP
           fetch_metadata_json(urls, label: "authorization server metadata")
         end
 
+        # The legacy authorization base is an origin, which a document may render as `https://host/`;
+        # both name the same server, and nothing else does.
+        def ensure_legacy_issuer_matches!(expected:, returned:)
+          return if returned == "#{expected}/"
+
+          ensure_issuer_matches!(expected: expected, returned: returned)
+        end
+
         # Reads `authorization_servers` from a PRM document and returns
         # the first entry, raising `AuthorizationError` for any of the malformed
         # shapes a non-compliant server could emit (missing field, non-Array
@@ -430,44 +617,63 @@ module MCP
           first
         end
 
-        # Walks candidate metadata URLs and returns the parsed JSON body of
-        # the first 2xx response. Raises `AuthorizationError` for transport
-        # failures (`Faraday::Error`) and malformed bodies (`JSON::ParserError`)
-        # so callers do not have to handle raw Faraday/JSON exceptions.
+        # Walks candidate metadata URLs and returns the parsed body of the first 2xx response that is a JSON object;
+        # the caller checks its fields. Candidates are tried until one serves such a body, since a later one may still
+        # be usable when an earlier one is broken or down (the URL from `WWW-Authenticate` against the well-known path,
+        # or the OAuth document against the OpenID one). Once the candidates are exhausted, an answer that said nothing
+        # about what is published (a network error, a `5xx`, or a `429`) outranks the rest and raises
+        # `MetadataUnreachableError`; otherwise (any other status, such as a `4xx` other than `429` or a redirect that
+        # was not followed, a body that is not JSON, or not a JSON object) `MetadataNotPublishedError`.
+        # A body over the cap is refused outright by `bounded_request` with a plain `AuthorizationError`,
+        # before any classification. Each failure is listed with its URL stripped of userinfo, query and fragment
+        # and cut to `METADATA_URL_MAX_LENGTH`, but otherwise spelled as requested, so it can be matched against
+        # a server's access log, and with exception text bounded, since the message lands in every log destination
+        # the error passes through.
         def fetch_metadata_json(urls, label:)
-          last_error = nil
+          failures = []
+          inconclusive = false
           urls.each do |url|
             response = begin
               http_get(url)
             rescue Faraday::Error => e
-              last_error = "GET #{url} raised #{e.class}: #{e.message}"
+              detail = bounded_diagnostic(e.message, limit: METADATA_DIAGNOSTIC_MAX_LENGTH)
+              failures << "GET #{reported_url(url)} raised #{[e.class, detail].compact.join(": ")}"
+              inconclusive = true
               next
             end
 
-            if response.status >= 200 && response.status < 300
-              parsed = begin
-                JSON.parse(response_body_string(response))
-              rescue JSON::ParserError => e
-                raise AuthorizationError, "Failed to parse #{label} from #{url}: #{e.message}."
-              end
+            unless response.status >= 200 && response.status < 300
+              failures << "GET #{reported_url(url)} returned #{response.status}"
+              inconclusive = true if response.status >= 500 || response.status == 429
+              next
+            end
 
-              # Even valid JSON can be the wrong shape (a top-level array,
-              # a bare `null`, a string, ...). The discovery callers index by
-              # name (`prm["authorization_servers"]`, etc.), so anything that
-              # is not a Hash would raise `TypeError` / `NoMethodError`
-              # downstream. Surface that as `AuthorizationError` instead so
-              # callers see a single, documented error type.
-              unless parsed.is_a?(Hash)
-                raise AuthorizationError,
-                  "#{label} from #{url} is not a JSON object (got #{parsed.class})."
-              end
+            parsed = begin
+              JSON.parse(response_body_string(response))
+            rescue JSON::ParserError => e
+              detail = bounded_diagnostic(e.message, limit: METADATA_DIAGNOSTIC_MAX_LENGTH) || e.class.name
+              failures << "GET #{reported_url(url)} returned a body that is not JSON: #{detail}"
+              next
+            end
 
-              return parsed
+            # Even valid JSON can be the wrong shape (a top-level array, a bare `null`, a string, ...).
+            # The discovery callers index by name (`prm["authorization_servers"]`, etc.), so anything that
+            # is not a Hash would raise `TypeError` / `NoMethodError` downstream.
+            unless parsed.is_a?(Hash)
+              failures << "GET #{reported_url(url)} returned a body that is not a JSON object (got #{parsed.class})"
+              next
             end
 
-            last_error = "GET #{url} returned #{response.status}"
+            return parsed
+          end
+
+          message = "Failed to fetch #{label}: #{failures.join("; ")}."
+
+          if inconclusive
+            raise MetadataUnreachableError, message
+          else
+            raise MetadataNotPublishedError, message
           end
-          raise AuthorizationError, "Failed to fetch #{label}: #{last_error}."
         end
 
         def ensure_pkce_supported!(as_metadata)
@@ -628,7 +834,7 @@ module MCP
           # (or the operator may rotate the CIMD URL), and a stale `client_information` entry would otherwise
           # keep sending the old CIMD URL forever. Re-evaluating on every flow re-reads the current AS metadata
           # and the current `provider.client_id_metadata_document_url`.
-          cimd_url = @provider.client_id_metadata_document_url
+          cimd_url = provider_client_id_metadata_document_url
           if cimd_url && as_metadata["client_id_metadata_document_supported"] == true
             return { "client_id" => cimd_url }
           end
@@ -758,6 +964,18 @@ module MCP
           MESSAGE
         end
 
+        # `Provider` tolerates tokens stored before the issuer was recorded (see `ensure_token_issuer!`).
+        # The `client_credentials` and `jwt-bearer` providers have no such tokens, since their refresh is new,
+        # and a refresh asks no validator, so a token without an `issuer` would be presented to whatever
+        # authorization server discovery names now. Refusing it sends the transport back through the grant,
+        # which does ask.
+        def ensure_refresh_token_issuer_recorded!
+          return if provider_authorization_flow == :authorization_code
+          return unless read_token("issuer").nil?
+
+          raise AuthorizationError, "Cannot refresh: the stored tokens record no issuer; re-authorization is required."
+        end
+
         def ensure_refreshable_client_information!(client_info, as_metadata:)
           stored_issuer = client_info_required_value(client_info, "issuer")
           return if stored_issuer.nil?
@@ -886,7 +1104,8 @@ module MCP
         def resolve_scope(scope:, prm:)
           return scope if scope && !scope.empty?
 
-          supported = prm["scopes_supported"]
+          # `prm` is nil on the legacy path, where nothing advertises scopes.
+          supported = prm && prm["scopes_supported"]
           return supported.join(" ") if supported.is_a?(Array) && !supported.empty?
 
           return @provider.scope if @provider.scope && !@provider.scope.empty?
@@ -948,6 +1167,31 @@ module MCP
           @provider.authorization_flow
         end
 
+        # Parameters the provider adds to every token request it makes (RFC 6749 Section 8.2 leaves room for them;
+        # Auth0's `audience` is the usual one). Duck-typed like `authorization_flow`, so a provider without the method,
+        # or one returning `nil`, adds nothing.
+        # A bad value raises `InvalidTokenRequestParamsError`, as the provider constructors do.
+        def provider_token_request_params
+          return {} unless @provider.respond_to?(:token_request_params)
+
+          params = @provider.token_request_params
+          return {} if params.nil?
+
+          problem = self.class.token_request_params_problem(params)
+          raise InvalidTokenRequestParamsError, "The provider's token_request_params #{problem}" if problem
+
+          params
+        end
+
+        # The Client ID Metadata Document URL, when the provider has one. Only `Provider` exposes the reader
+        # (CIMD replaces Dynamic Client Registration on the authorization-code flow), while `refresh!` serves
+        # every provider that holds a `refresh_token`, so the read is duck-typed like `authorization_flow`.
+        def provider_client_id_metadata_document_url
+          return unless @provider.respond_to?(:client_id_metadata_document_url)
+
+          @provider.client_id_metadata_document_url
+        end
+
         def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint
@@ -962,16 +1206,30 @@ module MCP
               "Authorization server metadata `authorization_endpoint` is not a valid URI: #{e.message}."
           end
 
-          params = URI.decode_www_form(uri.query.to_s)
-          params << ["response_type", "code"]
-          params << ["client_id", client_id]
-          params << ["redirect_uri", @provider.redirect_uri]
-          params << ["code_challenge", code_challenge]
-          params << ["code_challenge_method", "S256"]
-          params << ["state", state]
-          params << ["scope", scope] if scope
-          params << ["resource", resource] if resource
-          uri.query = URI.encode_www_form(params)
+          # A parameter the flow sets replaces any of the same name the endpoint URL already carries.
+          # RFC 6749 Section 3.1 forbids sending a parameter twice, and which of two values a server would honor is
+          # its own choice; on the legacy path the endpoint URL is served by the MCP server, whose query must not speak
+          # for the client's `client_id`, `redirect_uri`, `code_challenge`, or `resource`.
+          # Other parameters in the URL are kept, as the TypeScript SDK's `searchParams.set` keeps them; that includes
+          # a `scope` when the flow has none, since an authorization server may set a default scope there.
+          # RFC 9101 `request` and `request_uri` are dropped as well, though the flow sets neither: a server takes
+          # the whole authorization request from the object they carry, over every parameter in the query, and both are
+          # the client's to send, never an endpoint URL's to supply.
+          own_params = [
+            ["response_type", "code"],
+            ["client_id", client_id],
+            ["redirect_uri", @provider.redirect_uri],
+            ["code_challenge", code_challenge],
+            ["code_challenge_method", "S256"],
+            ["state", state],
+          ]
+          own_params << ["scope", scope] if scope
+          own_params << ["resource", resource] if resource
+          dropped_names = own_params.map(&:first) + ["request", "request_uri"]
+
+          params = URI.decode_www_form(uri.query.to_s).reject { |name, _value| dropped_names.include?(name) }
+          uri.query = URI.encode_www_form(params + own_params)
+
           uri
         end
 
@@ -997,9 +1255,12 @@ module MCP
           post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
         end
 
-        # Submits a form-encoded request to the token endpoint, applying
-        # the client authentication method advertised in `client_information` and
-        # adding `client_id` (and `client_secret` when not using HTTP Basic).
+        # Submits a form-encoded token request using the authentication method
+        # stored in `client_information`. The method determines whether client
+        # credentials belong in the form body, a Basic header, or a JWT assertion.
+        # A provider's `token_request_params` go underneath the flow's own parameters,
+        # which therefore win, and are refused before the request is sent when they name
+        # a reserved parameter or are not a Hash of Strings.
         def post_to_token_endpoint(as_metadata:, client_info:, form:)
           client_id = client_info_required_value(client_info, "client_id")
           unless client_id
@@ -1009,13 +1270,15 @@ module MCP
 
           client_secret = client_info_required_value(client_info, "client_secret")
           token_endpoint_auth_method = client_info_value(client_info, "token_endpoint_auth_method")
+          form = provider_token_request_params.merge(form)
 
-          form = if token_endpoint_auth_method == "private_key_jwt"
-            # RFC 7523 Section 2.2 JWT client assertion for the `private_key_jwt` method of
-            # the `io.modelcontextprotocol/oauth-client-credentials` extension (SEP-1046).
-            # The client identity travels in the assertion's `iss`/`sub` claims, so `client_id` is
-            # omitted from the body per RFC 7521 Section 4.2 (the `client_assertion` conveys the client identity).
-            # The audience is the issuer identifier that `ensure_issuer_matches!` already byte-validated.
+          # Apply one client authentication method per request (RFC 6749 Section 2.3).
+          headers = {}
+          form = case token_endpoint_auth_method
+          when "private_key_jwt"
+            # The assertion identifies the client through its `iss` and `sub`
+            # claims, so the body needs no separate `client_id` (RFC 7521 Section 4.2).
+            # Use the issuer already checked by `ensure_issuer_matches!` as the audience.
             unless @provider.respond_to?(:client_assertion)
               raise AuthorizationError,
                 "token_endpoint_auth_method is private_key_jwt but the provider does not " \
@@ -1026,22 +1289,24 @@ module MCP
               "client_assertion_type" => JWTClientAssertion::ASSERTION_TYPE,
               "client_assertion" => @provider.client_assertion(audience: as_metadata["issuer"]),
             )
+          when "client_secret_post"
+            # Send the client ID and available secret in the form body.
+            body = form.merge("client_id" => client_id)
+            body["client_secret"] = client_secret if client_secret
+            body
           else
-            form.merge("client_id" => client_id)
-          end
-
-          headers = {}
-          if client_secret
-            case token_endpoint_auth_method
-            when "client_secret_post"
-              form["client_secret"] = client_secret
-            when "none"
-              # Public client; no credential.
-            else
-              # RFC 6749 §2.3.1 recommends Basic for confidential clients and
-              # both Python and TypeScript SDKs default here when
-              # the authentication method is not explicitly stored.
+            if client_secret && token_endpoint_auth_method != "none"
+              # Basic is also the fallback when a secret is present but no method
+              # is stored. A body `client_id` is optional (RFC 6749 Section 3.2.1);
+              # omit it because some servers treat it alongside Basic as a second
+              # authentication method and reject the request with `invalid_request`.
               headers["Authorization"] = "Basic " + basic_auth_credentials(client_id, client_secret)
+              form
+            else
+              # With `none` or no secret, identify the client using `client_id`.
+              # This is required for unauthenticated authorization-code exchanges
+              # (RFC 6749 Section 3.2.1).
+              form.merge("client_id" => client_id)
             end
           end
 
@@ -1059,11 +1324,7 @@ module MCP
           end
 
           if response.status < 200 || response.status >= 300
-            if token_endpoint_error_code(response) == "invalid_grant"
-              raise InvalidGrantError, "Token endpoint rejected the grant: invalid_grant."
-            end
-
-            raise AuthorizationError, "Token endpoint returned status #{response.status}."
+            raise token_endpoint_error(response)
           end
 
           parsed = begin
@@ -1084,17 +1345,41 @@ module MCP
           parsed
         end
 
-        # Extracts the `error` code from an RFC 6749 §5.2 error response body
-        # when one is parseable. Returns nil on any parse failure or when
-        # the body is not JSON.
-        def token_endpoint_error_code(response)
-          body = response_body_string(response).to_s
-          return if body.empty?
+        # Surface only RFC 6749 §5.2 diagnostic fields, never the raw response,
+        # which may contain tokens or other credentials. Classify the original
+        # code so sanitization cannot turn malformed input into invalid_grant.
+        def token_endpoint_error(response)
+          message = "Token endpoint returned status #{response.status}."
+          error_class = AuthorizationError
+          parsed = JSON.parse(response_body_string(response))
+          parsed = {} unless parsed.is_a?(Hash)
+
+          error_class = parsed["error"] == "invalid_grant" ? InvalidGrantError : AuthorizationError
+          error = bounded_diagnostic(parsed["error"], limit: TOKEN_ENDPOINT_ERROR_MAX_LENGTH)
+          description = bounded_diagnostic(parsed["error_description"], limit: TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH)
+          message += " #{[error, description].compact.join(": ")}" if error || description
+
+          error_class.new(message, http_status: response.status, error: error, error_description: description)
+        rescue StandardError
+          # Diagnostics must not mask the endpoint failure or change refresh recovery.
+          error_class.new("Token endpoint returned status #{response.status}.", http_status: response.status)
+        end
+
+        def bounded_diagnostic(value, limit:)
+          return unless value.is_a?(String)
 
-          parsed = JSON.parse(body)
-          parsed["error"] if parsed.is_a?(Hash)
-        rescue JSON::ParserError
-          nil
+          # RFC 6749 permits printable ASCII except double quotes and backslashes in token endpoint error fields.
+          # Replace other characters to keep text received off the network on one log line.
+          value = value.scrub(" ").gsub(/[^\x20-\x21\x23-\x5B\x5D-\x7E]/, " ").strip
+          return if value.empty?
+
+          value.length > limit ? "#{value[0, limit - 3]}..." : value
+        end
+
+        # A candidate URL as it goes into a failure string: redacted, and cut so a URL the server chose cannot
+        # grow the message without limit.
+        def reported_url(url)
+          bounded_diagnostic(Discovery.redact_url(url), limit: METADATA_URL_MAX_LENGTH)
         end
 
         # Per RFC 6749 Section 2.3.1, the `client_id` and `client_secret` MUST be
@@ -1162,22 +1447,18 @@ module MCP
           @http_client ||= @http_client_factory.call
         end
 
-        # Deliberately built without redirect-following middleware. Every destination check in
-        # this class runs against the URL as written, before the request goes out, so a connection
-        # that transparently followed a `3xx` would let a server reach a host the checks just refused.
-        # A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
-        # and the guards above only cover the first hop.
-        #
-        # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
-        # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
-        # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
-        # after the check.
+        # A connection supplied through `http_client_factory:` replaces this one, the provider's customizer and
+        # `RequestedOriginGuard` included, so that caller takes on the redirect responsibility described on
+        # `build_http_client`; `bounded_request` caps its responses all the same.
         def default_http_client
-          require "faraday"
+          self.class.build_http_client(provider_http_client_customizer)
+        end
 
-          Faraday.new do |faraday|
-            faraday.headers["Accept"] = "application/json"
-          end
+        # `nil` for a provider that predates the hook or leaves it unset.
+        def provider_http_client_customizer
+          return unless @provider.respond_to?(:http_client_customizer)
+
+          @provider.http_client_customizer
         end
 
         def response_body_string(response)