ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/auth/oauth_provider/challenge_handling.rb

@@ -0,0 +1,532 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module MCPClient
+  module Auth
+    class OAuthProvider
+      # WWW-Authenticate challenge handling for {OAuthProvider}: parsing the
+      # challenge, fetching and validating the resource metadata it names,
+      # retiring tokens of another authorization server, and the checks a
+      # peer-advertised URL must pass. Mixed into OAuthProvider; every method
+      # relies on its state.
+      module ChallengeHandling
+        # One decimal, octal or hexadecimal component of a numeric IPv4 spec.
+        IPV4_COMPONENT = /\A(?:0x[0-9a-f]+|0[0-7]*|[1-9][0-9]*)\z/i
+
+        # A percent escape in a hostname.
+        PERCENT_ESCAPE = /%([0-9a-f]{2})/i
+
+        # How many times a host is percent-decoded before it is classified.
+        HOST_DECODE_PASSES = 4
+
+        # The characters a hostname or IP literal is spelled with: letters,
+        # digits, '-' and '.' for names, ':' for an IPv6 literal, '_' because
+        # resolvers and real deployments tolerate it in names.
+        HOSTNAME_CHARACTERS = /\A[a-z0-9\-._:]+\z/i
+
+        # Handle 401 Unauthorized response (for server discovery)
+        # @param response [Faraday::Response] HTTP response
+        # @return [ResourceMetadata, nil] Resource metadata if found
+        def handle_unauthorized_response(response)
+          www_authenticate = response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
+          return nil unless www_authenticate
+
+          # Challenge parameters are read from the Bearer challenge's own
+          # segment only — never from the whole (possibly multi-challenge)
+          # header — so parameters belonging to Basic or another scheme cannot
+          # drive Bearer scope selection or resource metadata discovery. A
+          # header without a Bearer challenge carries no usable Bearer params.
+          bearer_params = bearer_challenge_segment(www_authenticate)
+          # A header naming only schemes this client cannot answer — Basic,
+          # Negotiate — is not a Bearer challenge, so it says nothing about
+          # the scopes this resource wants and nothing about where its
+          # metadata lives. The reset below belongs to a Bearer challenge
+          # that carried no scope; letting a Basic 401 make it would drop the
+          # scope an insufficient_scope challenge required, and the step-up
+          # that follows would ask for less than the server demanded.
+          return nil unless bearer_params
+
+          # MCP 2025-11-25: "Clients MUST treat the scopes provided in the
+          # challenge as authoritative for satisfying the current request" —
+          # including resetting a previously challenged scope when the current
+          # challenge carries none.
+          url = extract_resource_metadata_url(www_authenticate)
+          scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
+          # A step-up challenge (403 insufficient_scope) says this operation
+          # needs more scopes, not that the authorization server moved: the
+          # token in hand stays valid (MCP 2026-07-28 step-up authorization).
+          # So whatever its resource metadata is worth — unfetchable, fetched
+          # and refused, or named by an unacceptable URL — the known server
+          # stays in place rather than becoming unknown (which would withhold
+          # that token from every other operation), and the challenged scope
+          # is recorded as the authoritative one. A challenge reporting an
+          # invalid token is judged in full, and a refused document stands.
+          step_up = step_up_challenge?(bearer_params)
+          previous = [@challenge_metadata_url, @challenge_resource_metadata, @challenge_error]
+
+          begin
+            # The challenge header is peer-controlled input: validate the
+            # advertised URL BEFORE storing, fetching, or recording any challenge
+            # state, so a malicious challenge cannot pivot this host into requests
+            # against internal services (SSRF) and cannot leave the provider
+            # holding half of a rejected challenge.
+            validate_peer_advertised_url!(url, 'resource metadata URL (from WWW-Authenticate challenge)') if url
+
+            @challenge_scope = scope
+            return nil unless url
+
+            # Remember the advertised URL even if the fetch below fails, so a
+            # later discovery retries it instead of probing well-known URIs the
+            # challenge already superseded. The current header is the one to
+            # honour: an earlier document, and an earlier refusal, are forgotten
+            # before the fetch so a failed fetch leaves the flow waiting on this
+            # URL rather than completing against stale state.
+            @challenge_metadata_url = url
+            @challenge_resource_metadata = nil
+            @challenge_error = nil
+            adopt_challenge_metadata(url)
+          rescue MCPClient::Errors::ConnectionError
+            raise unless step_up
+
+            @challenge_metadata_url, @challenge_resource_metadata, @challenge_error = previous
+            @challenge_scope = scope
+            raise
+          end
+        end
+
+        # Whether a Bearer challenge asks for more scopes (SEP-835 / MCP
+        # 2026-07-28 step-up), as opposed to reporting an invalid token.
+        # @param bearer_params [String, nil] the Bearer challenge's parameters
+        # @return [Boolean]
+        def step_up_challenge?(bearer_params)
+          bearer_params && extract_challenge_param(bearer_params, 'error') == 'insufficient_scope'
+        end
+
+        # Fetch, validate and adopt the resource metadata a challenge named.
+        # @param url [String] the advertised metadata URL
+        # @return [ResourceMetadata]
+        # @raise [MCPClient::Errors::ConnectionError] when the fetch fails or the document is refused
+        def adopt_challenge_metadata(url)
+          # This URL was explicitly advertised by the 401 challenge, so a 404 is a
+          # misconfiguration to surface (strict), not a speculative miss to skip.
+          metadata = fetch_resource_metadata(url, strict: true)
+          # Metadata discovery would reject is refused now, whole: it neither
+          # retires the token nor lingers as an authoritative challenge.
+          reject_unacceptable_challenge!(metadata)
+          # A validated challenge supersedes an earlier refused one.
+          @challenge_error = nil
+          # Reuse this challenge-advertised metadata during the subsequent OAuth
+          # flow instead of re-deriving (and possibly missing) the well-known URL.
+          @challenge_resource_metadata = metadata
+          revoke_token_on_authorization_server_change(metadata)
+          metadata
+        end
+
+        # A challenge whose metadata could not be fetched yet is retried before
+        # any token is judged: until it resolves, the current authorization
+        # server is unknown and nothing is presented.
+        # @return [void]
+        def resolve_pending_challenge
+          return unless @challenge_metadata_url && @challenge_resource_metadata.nil?
+
+          adopt_challenge_metadata(@challenge_metadata_url)
+        rescue MCPClient::Errors::ConnectionError => e
+          logger.debug("Challenge metadata still unresolved: #{e.message}")
+        end
+
+        # A challenge naming another authorization server than the one the
+        # stored token came from retires that token at once: it is never
+        # presented again, whatever the storage backend can do.
+        # @param resource_metadata [ResourceMetadata]
+        # @return [void]
+        def revoke_token_on_authorization_server_change(resource_metadata)
+          advertised = Array(resource_metadata&.authorization_servers).first
+          known = stored_server_metadata&.issuer
+          return unless advertised && known && advertised != known
+
+          @authorization_server_switched = true
+          # Ending the pending requests and retiring the token are one step
+          # against the responses being accepted meanwhile: a code exchange or
+          # refresh that has passed its checks holds this lock until its token
+          # is written, so it is never this transition that lands in between
+          # (see {MCPClient::Auth::OAuthProvider#with_authorization_state_lock}).
+          with_authorization_state_lock do
+            # The requests still pending with the server this resource left can
+            # never complete as this resource's: ended now, before anything is
+            # fetched from the advertised server, so a late answer to them is
+            # refused by every provider sharing the storage.
+            end_pending_requests_of(known)
+            # A token another provider sharing the storage already bound to the
+            # advertised server is exactly the token to keep.
+            next if record_bound_to?(stored_token_or_nil, advertised)
+
+            logger.debug('The challenge names another authorization server; retiring the stored token')
+            delete_token(bind_to: Token::RETIRED_ISSUER)
+          end
+        end
+
+        # Apply the checks discovery applies to challenge-advertised resource
+        # metadata (resource identity, an acceptable authorization server URL)
+        # before anything acts on it; a failing document refuses the whole
+        # challenge (see {#reject_challenge!}).
+        # @param resource_metadata [ResourceMetadata]
+        # @return [void]
+        # @raise [MCPClient::Errors::ConnectionError] when the challenge is refused
+        def reject_unacceptable_challenge!(resource_metadata)
+          begin
+            validate_resource_matches!(resource_metadata)
+          rescue MCPClient::Errors::ConnectionError => e
+            reject_challenge!(e.message)
+          end
+          advertised = Array(resource_metadata.authorization_servers).first
+          unless advertised
+            reject_challenge!('Protected resource metadata does not advertise any authorization_servers')
+          end
+
+          validate_peer_advertised_url!(advertised, 'authorization server URL (from resource metadata)')
+        end
+
+        # Extract the protected-resource-metadata URL from a WWW-Authenticate header.
+        # Per RFC 9728 the parameter is `resource_metadata`; a legacy `resource`
+        # parameter is accepted as a fallback for older servers. Only the Bearer
+        # challenge's own segment is consulted, so a parameter belonging to
+        # another scheme's challenge can never drive discovery.
+        # @param header [String] the WWW-Authenticate header value
+        # @return [String, nil] the metadata URL if present
+        def extract_resource_metadata_url(header)
+          # A URL is not free text. RFC 3986 spells a URI in ASCII, so a
+          # header this client had to scrub to read did not advertise one:
+          # every undecodable byte in it became a '?', and fetching that
+          # rewriting would send a request to a URL nobody wrote. The
+          # challenge simply names no metadata URL, and discovery falls back
+          # to the well-known URIs.
+          return nil unless PeerText.decodable?(header)
+
+          params = bearer_challenge_segment(header)
+          return nil unless params
+
+          # Auth-params may include optional whitespace around '=' (RFC 7235).
+          # Quoted form: resource_metadata = "https://..."
+          if (m = params.match(/resource_metadata\s*=\s*"([^"]+)"/))
+            return m[1]
+          end
+
+          # Unquoted token form: resource_metadata = https://...
+          if (m = params.match(/resource_metadata\s*=\s*([^,\s]+)/))
+            return m[1]
+          end
+
+          # Legacy fallback: resource="https://.../.well-known/oauth-protected-resource"
+          legacy = params.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
+          legacy if legacy && protected_resource_metadata_url?(legacy)
+        end
+
+        # RFC 9728 names the challenge parameter `resource_metadata`; a
+        # `resource` parameter is a resource identifier (RFC 8707), not a
+        # document. It is read as a metadata URL only when it points at a
+        # protected resource metadata well-known location — read as one
+        # otherwise, the MCP endpoint itself would be fetched as metadata,
+        # fail, and stand in the way of the well-known fallback MCP
+        # 2026-07-28 requires when the challenge names no document.
+        # @param url [String] the parameter value
+        # @return [Boolean]
+        def protected_resource_metadata_url?(url)
+          URI.parse(url).path.to_s.include?('/.well-known/oauth-protected-resource')
+        rescue URI::InvalidURIError
+          false
+        end
+
+        # Extract the Bearer challenge's own parameter segment from a (possibly
+        # multi-challenge) WWW-Authenticate header, so params belonging to other
+        # schemes (e.g. `Basic resource_metadata="...", Bearer realm="x"`) are
+        # never attributed to the Bearer challenge. Mirrors
+        # HttpTransportBase#bearer_challenge_segment.
+        # @param header [String, nil] the WWW-Authenticate header value
+        # @return [String, nil] the Bearer challenge's parameters (possibly
+        #   empty), or nil when the header has no Bearer challenge
+        def bearer_challenge_segment(header)
+          # A header value is peer bytes, and `gsub`, `match` and `[]` all
+          # raise `ArgumentError` on bytes that are not valid UTF-8 — out of
+          # the 401 handler, which would then report the client's own
+          # ArgumentError instead of the challenge. It is made decodable
+          # before it is read; nothing else about it is changed, because the
+          # URL and scope this parser returns have to be what the peer wrote.
+          header = matchable_peer_text(header)
+          return nil unless header
+
+          # Locate the Bearer scheme token only OUTSIDE quoted strings: a
+          # quoted value such as realm="prefix Bearer x" must not anchor the
+          # segment.
+          masked = header.gsub(/"(?:\\.|[^"\\])*"/) { |q| "\"#{' ' * (q.length - 2)}\"" }
+          match = masked.match(/(?:\A|[\s,])Bearer(?=[\s,]|\z)/i)
+          return nil unless match
+
+          header[match.end(0)..][AUTH_PARAMS_RUN]
+        end
+
+        # Extract an auth-param value from a WWW-Authenticate header
+        # (quoted or unquoted form, optional whitespace around '=').
+        # @param header [String] the WWW-Authenticate header value
+        # @param name [String] the auth-param name
+        # @return [String, nil] the parameter value if present
+        def extract_challenge_param(header, name)
+          header = matchable_peer_text(header)
+          return nil unless header
+
+          if (m = header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*"([^"]*)"/i))
+            return m[1]
+          end
+
+          header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*([^,\s]+)/i)&.captures&.first
+        end
+
+        private
+
+        # Validate a URL that a peer advertised to us (a 401 challenge's
+        # resource_metadata, or PRM authorization_servers).
+        #
+        # Stricter than enforce_https!, which exists for URLs the OPERATOR
+        # configured and therefore tolerates plain-HTTP loopback for local
+        # development. Applying that exception to peer-supplied input would
+        # leave the reported SSRF intact against the most sensitive targets of
+        # all — services listening only on localhost. It is honored here only
+        # for a loopback MCP server naming a loopback target: the developer is
+        # already pointed at a local stack, and that stack may advertise
+        # another port of itself over plain HTTP. Nothing wider qualifies. A
+        # server on a private network ('10.0.0.5', 'app.internal') is remote
+        # as far as this check is concerned, and even a loopback server may not
+        # send us to a link-local or private address — '169.254.169.254' is our
+        # cloud metadata endpoint, not the MCP server's.
+        #
+        # A refusal of a CHALLENGE-advertised URL is recorded (latch: true) so a
+        # later discovery fails closed instead of silently reusing cached
+        # authorization-server metadata. A refusal of a document found by
+        # speculative well-known discovery records nothing: there is no cache to
+        # protect, and latching it would leave a server that is later fixed
+        # unreachable for the life of this provider.
+        #
+        # NOTE: hostnames are checked literally. This does not resolve DNS, so a
+        # public name that resolves to a private address is not caught here;
+        # that needs resolution-time checking in the HTTP layer.
+        # @param url [String] the peer-advertised URL
+        # @param label [String] human-readable name for errors
+        # @param latch [Boolean] whether a refusal is recorded as an authoritative
+        #   challenge refusal (true for a 401 challenge, false for speculative
+        #   well-known discovery, which must stay retryable)
+        # @raise [MCPClient::Errors::ConnectionError] if the URL is not acceptable
+        def validate_peer_advertised_url!(url, label, latch: true)
+          uri = URI.parse(url)
+          host = uri.hostname.to_s.downcase
+
+          # The whole development exception, in one predicate: a loopback
+          # target advertised to a client whose configured server is loopback.
+          local_stack = loopback_address?(host) && loopback_server?
+
+          if uri.scheme != 'https' && !(uri.scheme == 'http' && local_stack)
+            refuse_peer_url!("OAuth #{label} must use HTTPS: #{safe_error_text(url)}", latch: latch)
+          end
+          # An authority-less URL ('https:foo', 'https:///foo') has an acceptable
+          # scheme and an empty host, so it would otherwise pass every check
+          # below and be treated as a validated authorization server — enough to
+          # retire the stored token before discovery can only fail.
+          refuse_peer_url!("OAuth #{label} must name a host: #{safe_error_text(url)}", latch: latch) if host.empty?
+          if local_address?(host) && !local_stack
+            refuse_peer_url!("OAuth #{label} must not target a loopback or private address: #{safe_error_text(url)}",
+                             latch: latch)
+          end
+          # Anything left that a resolver could not look up as a name — an
+          # undecodable escape, a NUL, a slash smuggled in as '%2f' — is not a
+          # host we can classify, so it is refused rather than handed to the
+          # HTTP client to interpret.
+          return if hostname_shaped?(normalize_host(host))
+
+          refuse_peer_url!("OAuth #{label} must name a valid host: #{safe_error_text(url)}", latch: latch)
+        rescue URI::InvalidURIError
+          refuse_peer_url!("OAuth #{label} is not a valid URL: #{safe_error_text(url)}", latch: latch)
+        end
+
+        # @param message [String] why the peer-advertised URL was refused
+        # @param latch [Boolean] whether to record the refusal for later discovery
+        # @raise [MCPClient::Errors::ConnectionError] always
+        def refuse_peer_url!(message, latch:)
+          reject_challenge!(message) if latch
+
+          # A speculative document is not latched, but it is still refused: the
+          # copy fetch_resource_metadata kept for scope resolution must go too,
+          # or its scopes_supported would be sent in the registration and
+          # authorization requests of a flow that discarded the document.
+          @resource_metadata = nil
+          raise MCPClient::Errors::ConnectionError, message
+        end
+
+        # @return [Boolean] whether the resource metadata being acted on was
+        #   advertised by a 401 challenge (authoritative) rather than found by
+        #   speculative well-known discovery
+        def challenge_advertised_metadata?
+          !(@challenge_resource_metadata.nil? && @challenge_metadata_url.nil?)
+        end
+
+        # @param message [String] why the challenge was refused
+        # @raise [MCPClient::Errors::ConnectionError] always
+        def reject_challenge!(message)
+          # Drop every scrap of the refused challenge so nothing half-applied
+          # survives, and remember why for the next discovery attempt.
+          @challenge_scope = nil
+          @challenge_metadata_url = nil
+          @challenge_resource_metadata = nil
+          @resource_metadata = nil
+          @challenge_error = message
+          raise MCPClient::Errors::ConnectionError, message
+        end
+
+        # The development exception is for a developer pointed at a local
+        # stack, so it asks for loopback and nothing else: a server on the
+        # office network ('10.0.0.5', 'app.internal', 'printer.local') is as
+        # remote as a public one, and its 401 must not be able to name the
+        # client's own localhost or the cloud metadata endpoint.
+        # @return [Boolean] whether the configured MCP server is on the
+        #   loopback interface, in which case loopback discovery targets are
+        #   expected
+        def loopback_server?
+          loopback_address?(URI.parse(server_url).hostname.to_s.downcase)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        # The one definition of "loopback" in this client: 'localhost' and its
+        # subdomains, which RFC 6761 reserves for the loopback interface and
+        # every resolver answers as 127.0.0.1 / ::1, plus any loopback address
+        # (127.0.0.0/8, ::1) in any spelling the resolver accepts. Shared by
+        # the SSRF classifier, the registered application_type and the
+        # plain-HTTP exception for configured and discovered endpoints, so all
+        # three agree on what a local stack is.
+        # @param host [String] a hostname
+        # @return [Boolean] whether it names the loopback interface
+        def loopback_address?(host)
+          host = normalize_host(host)
+          return true if LOOPBACK_HOSTS.include?(host) || host.end_with?('.localhost')
+
+          ip = parse_address(host)
+          return false unless ip
+
+          ip = ip.native if ip.ipv6? && (ip.ipv4_mapped? || ip.ipv4_compat?)
+          ip.loopback?
+        end
+
+        # @param host [String] a hostname
+        # @return [Boolean] whether it names a loopback, private or link-local address
+        def local_address?(host)
+          return true if loopback_address?(host)
+
+          host = normalize_host(host)
+          return true if host.end_with?('.local', '.internal')
+
+          local_ip?(host)
+        end
+
+        # A host is classified by the name a resolver would look up: URI#hostname
+        # does not percent-decode, but the HTTP client dials the decoded name,
+        # so '169.254.169.254%2e', '127%2e0%2e0%2e1' and '%31%32%37.0.0.1' all
+        # reach 127.0.0.1 / the metadata endpoint and must classify as those.
+        # Decoding comes first; then the brackets of an IPv6 literal, which are
+        # punctuation, and a single trailing dot, which only marks the name as
+        # fully qualified. Case folding comes last: decoding can put letters
+        # back that the caller's downcase already passed over ('%4Cocalhost'
+        # decodes to 'Localhost'), and hostnames are case-insensitive.
+        # @param host [String] a hostname as it was written in the URL
+        # @return [String] the decoded, downcased host, brackets and one
+        #   trailing dot removed
+        def normalize_host(host)
+          percent_decode_host(host.to_s).delete_prefix('[').delete_suffix(']').delete_suffix('.').downcase
+        end
+
+        # Decoding is repeated until the host stops changing so a doubly encoded
+        # spelling ('%252e') cannot hide behind one pass, and capped so a host
+        # of nothing but escapes cannot spin. A malformed or non-ASCII escape is
+        # left alone: it survives as a literal '%', which hostname_shaped?
+        # refuses.
+        # @param host [String] a hostname as it was written in the URL
+        # @return [String] the host with its ASCII percent escapes resolved
+        def percent_decode_host(host)
+          HOST_DECODE_PASSES.times do
+            break unless host.include?('%')
+
+            decoded = host.gsub(PERCENT_ESCAPE) do |escape|
+              byte = ::Regexp.last_match(1).hex
+              byte < 0x80 ? byte.chr : escape
+            end
+            break if decoded == host
+
+            host = decoded
+          end
+          host
+        end
+
+        # @param host [String] a normalized (decoded, unbracketed) hostname
+        # @return [Boolean] whether it is spelled with the characters a
+        #   hostname or IP literal may contain
+        def hostname_shaped?(host)
+          !host.empty? && host.match?(HOSTNAME_CHARACTERS)
+        end
+
+        # Classify a literal address semantically rather than by spelling: a
+        # prefix list misses the forms IPv6 permits for the very ranges it
+        # means to reject ('::ffff:169.254.169.254' for the link-local metadata
+        # endpoint, '0:0:0:0:0:0:0:1' for loopback), so parse the host and ask
+        # IPAddr. IPv4-mapped and IPv4-compatible addresses are folded to their
+        # IPv4 form first, so one set of range checks covers both families.
+        # @param host [String] a hostname with any brackets already stripped
+        # @return [Boolean] whether it is a literal address in a local range
+        def local_ip?(host)
+          ip = parse_address(host)
+          return false unless ip
+
+          ip = ip.native if ip.ipv6? && (ip.ipv4_mapped? || ip.ipv4_compat?)
+          # 0.0.0.0 / :: name "this host" and are neither loopback nor private
+          # to IPAddr, but reach local services just the same.
+          return true if ip.to_i.zero?
+
+          ip.loopback? || ip.link_local? || ip.private?
+        end
+
+        # @param host [String] a hostname
+        # @return [IPAddr, nil] the address it names, or nil when it is a name
+        def parse_address(host)
+          IPAddr.new(host)
+        rescue ArgumentError # IPAddr::Error included
+          # IPAddr only accepts dotted quads, but the resolver (inet_aton) also
+          # accepts shorthand and alternate radixes — '127.1', '0177.0.0.1',
+          # '0x7f.0.0.1' and '2130706433' all reach 127.0.0.1 — so a check that
+          # stopped at IPAddr would wave those straight through.
+          shorthand_ipv4(host)
+        end
+
+        # @param host [String] a hostname
+        # @return [IPAddr, nil] the address inet_aton would read, when the host
+        #   is a numeric IPv4 spec IPAddr itself rejects
+        def shorthand_ipv4(host)
+          parts = host.split('.', -1)
+          return nil unless (1..4).cover?(parts.size) && parts.all? { |part| part.match?(IPV4_COMPONENT) }
+
+          values = parts.map { |part| Integer(part, ipv4_component_base(part)) }
+          # inet_aton: the last component fills every byte the earlier ones left.
+          last = values.pop
+          return nil if last >= (1 << (8 * (4 - values.size))) || values.any? { |value| value > 255 }
+
+          IPAddr.new(values.each_with_index.sum { |value, i| value << (8 * (3 - i)) } + last, Socket::AF_INET)
+        rescue ArgumentError
+          nil
+        end
+
+        # @param part [String] one component of a numeric IPv4 spec
+        # @return [Integer] its radix (leading '0x' hex, leading '0' octal, else decimal)
+        def ipv4_component_base(part)
+          return 16 if part.downcase.start_with?('0x')
+
+          part.start_with?('0') ? 8 : 10
+        end
+      end
+    end
+  end
+end

data/lib/mcp_client/auth/oauth_provider/client_authentication.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'uri'
+
+module MCPClient
+  module Auth
+    class OAuthProvider
+      # How this client authenticates at the token endpoint.
+      #
+      # A confidential client — one the authorization server issued a
+      # `client_secret` to — must present that secret with every token
+      # request, and RFC 7591 Section 2 says how: "if unspecified or omitted,
+      # the default is `client_secret_basic`". This client used to send the
+      # secret only for `client_secret_post` and to record an omitted method
+      # as `none`, which is the one combination that never authenticates: a
+      # registration that issued a secret and named no method produced a
+      # record whose secret was never sent, and every token request went out
+      # as an unauthenticated client for an authorization server that expects
+      # HTTP Basic.
+      #
+      # So the method the authorization server registered decides, defaulting
+      # as the RFC does:
+      #
+      # * `client_secret_basic` — the credentials go in an `Authorization:
+      #   Basic` header, form-urlencoded before they are base64'd (RFC 6749
+      #   Section 2.3.1), never in the body;
+      # * `client_secret_post` — in the request body, as before;
+      # * `none` (a public client, or no secret at all) — nothing is sent;
+      # * anything else (`private_key_jwt`, `client_secret_jwt`, a method a
+      #   future RFC adds) — this client cannot produce that assertion, so it
+      #   sends no credentials and says so, rather than guessing with the
+      #   secret in a header the server did not ask for.
+      #
+      # Mixed into OAuthProvider.
+      module ClientAuthentication
+        # RFC 7591 Section 2: the `token_endpoint_auth_method` a registration
+        # response that names none is read as.
+        DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD = 'client_secret_basic'
+
+        # The method a public client declares: no credentials are sent.
+        NO_CLIENT_AUTHENTICATION = 'none'
+
+        private
+
+        # The `token_endpoint_auth_method` to record for a registration
+        # response. RFC 7591 Section 2's default applies to a client the
+        # server issued a secret to; a registration without one is the public
+        # client this library asks to be.
+        # @param data [Hash] the parsed registration response
+        # @return [String]
+        def registered_auth_method(data)
+          method = data['token_endpoint_auth_method']
+          return method if method.is_a?(String) && !method.empty?
+
+          client_secret_bytes?(data['client_secret']) ? DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD : NO_CLIENT_AUTHENTICATION
+        end
+
+        # Add this client's credentials to a token request the way the
+        # authorization server registered them.
+        # @param params [Hash] the form parameters, extended in place for client_secret_post
+        # @param client_info [ClientInfo] the credentials to present
+        # @return [String, nil] the `Authorization` header value to send, if any
+        def apply_client_credentials!(params, client_info)
+          method = token_endpoint_auth_method_for(client_info)
+          case method
+          when nil, NO_CLIENT_AUTHENTICATION
+            nil
+          when 'client_secret_post'
+            params[:client_secret] = client_info.client_secret
+            nil
+          when DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD
+            basic_authorization_header(client_info.client_id, client_info.client_secret)
+          else
+            logger.warn('The authorization server registered token_endpoint_auth_method ' \
+                        "#{safe_error_text(method.to_s).inspect}, which this client cannot present; " \
+                        'the token request is made without client authentication')
+            nil
+          end
+        end
+
+        # The method to authenticate these credentials with. A client without
+        # a secret authenticates with nothing whatever its metadata says; a
+        # client WITH one falls back to RFC 7591's default, which also covers
+        # a record persisted before this client read the field (stored as
+        # `none` alongside a secret, a combination that authenticates
+        # nowhere).
+        # @param client_info [ClientInfo]
+        # @return [String, nil] the method, or nil when nothing is to be sent
+        def token_endpoint_auth_method_for(client_info)
+          return nil unless client_secret_bytes?(client_info.client_secret)
+
+          method = client_info.metadata.token_endpoint_auth_method
+          return DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD unless method.is_a?(String) && !method.empty?
+          return DEFAULT_TOKEN_ENDPOINT_AUTH_METHOD if method == NO_CLIENT_AUTHENTICATION
+
+          method
+        end
+
+        # RFC 6749 Section 2.3.1: the client identifier and secret are encoded
+        # with `application/x-www-form-urlencoded` and then, joined by a
+        # single colon, base64-encoded — so a `:` or a space in either does
+        # not shift the boundary the server splits on.
+        # @param client_id [String]
+        # @param client_secret [String]
+        # @return [String] the `Authorization` header value
+        def basic_authorization_header(client_id, client_secret)
+          credentials = "#{URI.encode_www_form_component(client_id.to_s)}:" \
+                        "#{URI.encode_www_form_component(client_secret.to_s)}"
+          "Basic #{Base64.strict_encode64(credentials)}"
+        end
+
+        # @param value [Object, nil] a candidate client secret
+        # @return [Boolean] whether it is a secret this client could present
+        def client_secret_bytes?(value)
+          value.is_a?(String) && !value.empty?
+        end
+      end
+    end
+  end
+end