mcp 1.7.0 → 1.8.0

data/lib/mcp/server/oauth/authenticator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "access_token"
+require_relative "challenge"
+require_relative "errors"
+
+module MCP
+  class Server
+    module OAuth
+      # The verification core shared by `Middleware` and the streamable HTTP transport's built-in enforcement:
+      # extracts the bearer token from a Rack env, runs it through the verifier, checks scopes, and maps each failure
+      # to the RFC 6750 challenge response it deserves.
+      #
+      # - `token_verifier` - anything responding to `verify(token)`; see `TokenVerifier` for the contract.
+      #   Built-ins: `JWTVerifier`, `IntrospectionVerifier`.
+      # - `required_scopes` - scopes the token must include, all of them; a shortfall produces 403 `insufficient_scope` (step-up).
+      # - `resource_metadata` - a `ProtectedResourceMetadata`; its well-known URL and `scopes_supported` feed the challenges.
+      #   Pass `resource_metadata_url:` instead to point at a document served elsewhere.
+      # - `scope_matcher` - optional callable `(required_scope, granted_scopes) -> Boolean` for deployments
+      #   whose scopes form a hierarchy; the MCP authorization specification requires a broader scope to satisfy
+      #   the narrower scopes it implies, which exact membership (the default) cannot express. The matcher also rides
+      #   on the returned `AccessToken`, so `require_scopes!` and `scope?` inside handlers apply the same semantics.
+      class Authenticator
+        # RFC 6750 Section 2.1: the scheme and the token are separated by spaces (`1*SP`), never by other whitespace.
+        BEARER_PATTERN = /\ABearer +(?<token>\S+)\z/i.freeze
+        # Whether the header names the Bearer scheme at all, well-formed or not. `Bearer` followed by anything other
+        # than a space names no Bearer credentials, the way the Python and TypeScript servers read it.
+        BEARER_SCHEME_PATTERN = /\ABearer(?: |\z)/i.freeze
+        private_constant :BEARER_PATTERN, :BEARER_SCHEME_PATTERN
+
+        # Upper bound on the presented token, applied before any verification so oversized garbage neither reaches
+        # cryptographic parsing nor gets forwarded to an introspection endpoint. Real-world access tokens stay far below this;
+        # web servers cap the whole header section around 16 KiB.
+        MAX_TOKEN_BYTES = 8192
+
+        def initialize(token_verifier:, required_scopes: [], resource_metadata: nil, resource_metadata_url: nil, scope_matcher: nil)
+          @verifier = token_verifier
+          @required_scopes = Array(required_scopes)
+          @resource_metadata = resource_metadata
+          @resource_metadata_url = resource_metadata_url || resource_metadata&.well_known_url
+          @scope_matcher = scope_matcher
+        end
+
+        # @param env [Hash] the Rack env
+        # @return [AccessToken]
+        # @raise [MissingTokenError, InvalidRequestError, InvalidTokenError, InsufficientScopeError]
+        def authenticate(env)
+          token = extract_bearer_token(env)
+
+          access_token = @verifier.verify(token)
+          raise InvalidTokenError if access_token.nil?
+
+          access_token = attach_scope_matcher(access_token)
+          check_scopes!(access_token)
+          access_token
+        end
+
+        # Maps an `OAuth::Error` raised by `authenticate` (or by a handler's `require_scopes!`) to the Rack response carrying
+        # the matching challenge. An `Error` outside the four built-in classes, such as one a custom verifier defines,
+        # is a token rejection and answers 401 like an invalid token; anything else is a programming error.
+        def challenge_response(error)
+          case error
+          when MissingTokenError
+            Challenge.missing_token_response(scope: scope_hint, resource_metadata: @resource_metadata_url)
+          when InvalidRequestError
+            Challenge.invalid_request_response(error_description: error.message, resource_metadata: @resource_metadata_url)
+          when InsufficientScopeError
+            Challenge.insufficient_scope_response(
+              error_description: error.message,
+              scope: scope_hint(error.required_scopes),
+              resource_metadata: @resource_metadata_url,
+            )
+          when Error
+            Challenge.invalid_token_response(
+              error_description: error.message,
+              scope: scope_hint,
+              resource_metadata: @resource_metadata_url,
+            )
+          else
+            raise ArgumentError, "unexpected error class: #{error.class}"
+          end
+        end
+
+        private
+
+        def extract_bearer_token(env)
+          header = env["HTTP_AUTHORIZATION"]
+          raise MissingTokenError if header.nil? || header.empty?
+
+          # Matched as bytes: a Rack server hands the header over as ASCII-8BIT, but a test request or a framework can tag it UTF-8,
+          # and a regexp raises on an invalid byte sequence in a UTF-8 string. As bytes, such a token simply fails verification.
+          bytes = header.b
+
+          # A header naming another scheme carries no Bearer credentials: RFC 6750 Section 3.1 counts a request that
+          # "attempted using an unsupported authentication method" among those lacking authentication information,
+          # which get the bare challenge, and the Python and TypeScript servers answer it 401 as well.
+          # A header that names Bearer but is malformed is a bad request (`invalid_request` in the same section).
+          raise MissingTokenError unless BEARER_SCHEME_PATTERN.match?(bytes)
+
+          match = BEARER_PATTERN.match(bytes)
+          raise InvalidRequestError, "Authorization header must carry a single Bearer token" if match.nil?
+
+          token = match[:token]
+          raise InvalidTokenError, "Token exceeds the maximum accepted length" if token.bytesize > MAX_TOKEN_BYTES
+
+          token
+        end
+
+        def check_scopes!(access_token)
+          missing_scopes = @required_scopes.reject { |scope| scope_satisfied?(scope, access_token) }
+          return if missing_scopes.empty?
+
+          raise InsufficientScopeError.new(
+            "Token is missing required scopes: #{missing_scopes.join(", ")}",
+            required_scopes: @required_scopes,
+          )
+        end
+
+        # A verifier result that is not an `AccessToken` (a duck-typed object from a custom verifier) keeps its own `scope?`;
+        # the endpoint gate below still applies the matcher to it directly.
+        def attach_scope_matcher(access_token)
+          return access_token if @scope_matcher.nil? || !access_token.respond_to?(:with_scope_matcher)
+
+          access_token.with_scope_matcher(@scope_matcher)
+        end
+
+        # A verifier result without a `scopes` reader (a duck-typed object offering only `scope?`) keeps its own judgement,
+        # since the matcher needs the granted list to reason about a hierarchy.
+        def scope_satisfied?(scope, access_token)
+          return access_token.scope?(scope) if @scope_matcher.nil? || !access_token.respond_to?(:scopes)
+
+          @scope_matcher.call(scope, access_token.scopes)
+        end
+
+        # The scope hint the spec recommends including in challenges: the scopes of the failing operation when known,
+        # the scopes this authenticator enforces otherwise, or the resource's advertised scopes as a fallback.
+        # `offline_access` is never advertised: refresh token issuance is not a resource requirement per
+        # the MCP authorization specification.
+        def scope_hint(operation_scopes = [])
+          scopes = operation_scopes
+          scopes = @required_scopes if scopes.empty?
+          scopes = Array(@resource_metadata&.scopes_supported) if scopes.empty?
+          scopes -= ["offline_access"]
+
+          scopes.empty? ? nil : scopes.join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/challenge.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MCP
+  class Server
+    module OAuth
+      # Stateless builders for RFC 6750 Bearer challenges and the Rack error responses that carry them.
+      # `Authenticator` uses these for every rejection; they are also public so custom integrations can emit
+      # spec-shaped 401/403 responses without pulling in the middleware.
+      #
+      # The header output is the exact counterpart of `MCP::Client::OAuth::Discovery.parse_www_authenticate`:
+      # everything built here parses back into the same parameters on the client side.
+      # https://www.rfc-editor.org/rfc/rfc6750#section-3
+      module Challenge
+        CONTENT_TYPE_JSON = { "content-type" => "application/json" }.freeze
+        private_constant :CONTENT_TYPE_JSON
+
+        class << self
+          # Returns a `WWW-Authenticate` header value such as
+          # `Bearer error="invalid_token", error_description="...", scope="a b", resource_metadata="https://..."`.
+          # Parameters are quoted-string encoded per RFC 7235; nil parameters are omitted.
+          def build(error: nil, error_description: nil, scope: nil, resource_metadata: nil)
+            parameters = []
+            parameters << %(error="#{quote(error)}") if error
+            parameters << %(error_description="#{quote(error_description)}") if error_description
+            parameters << %(scope="#{quote(scope)}") if scope
+            parameters << %(resource_metadata="#{quote(resource_metadata)}") if resource_metadata
+
+            parameters.empty? ? "Bearer" : "Bearer #{parameters.join(", ")}"
+          end
+
+          # 401 with `error="invalid_token"`: the presented token is expired, revoked, or otherwise invalid.
+          # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+          def invalid_token_response(error_description: nil, scope: nil, resource_metadata: nil)
+            challenge_response(
+              401,
+              error: "invalid_token",
+              error_description: error_description,
+              scope: scope,
+              resource_metadata: resource_metadata,
+            )
+          end
+
+          # 401 without an error code: RFC 6750 Section 3.1 says the challenge answering a request that
+          # carried no authentication information at all should not include an error code or other error information.
+          # A request that tried another scheme counts as one (the same section).
+          def missing_token_response(scope: nil, resource_metadata: nil)
+            challenge_response(401, scope: scope, resource_metadata: resource_metadata)
+          end
+
+          # 403 with `error="insufficient_scope"`: the token is valid but lacks a scope the current operation requires.
+          # Clients treat this as a step-up signal and re-authorize with the scopes advertised in `scope`.
+          def insufficient_scope_response(error_description: nil, scope: nil, resource_metadata: nil)
+            challenge_response(
+              403,
+              error: "insufficient_scope",
+              error_description: error_description,
+              scope: scope,
+              resource_metadata: resource_metadata,
+            )
+          end
+
+          # 400 with `error="invalid_request"`: the request itself is malformed (e.g. a `Bearer` header without exactly one token).
+          def invalid_request_response(error_description: nil, resource_metadata: nil)
+            challenge_response(
+              400,
+              error: "invalid_request",
+              error_description: error_description,
+              resource_metadata: resource_metadata,
+            )
+          end
+
+          private
+
+          def challenge_response(status, error: nil, error_description: nil, scope: nil, resource_metadata: nil)
+            # The description reaches the header (quoted below) and the JSON body alike; normalized once here
+            # so a custom verifier's message with invalid bytes cannot make `to_json` raise either.
+            error_description = utf8(error_description) if error_description
+            www_authenticate = build(
+              error: error,
+              error_description: error_description,
+              scope: scope,
+              resource_metadata: resource_metadata,
+            )
+            return [status, { "www-authenticate" => www_authenticate }, []] if error.nil?
+
+            body = { error: error }
+            body[:error_description] = error_description if error_description
+
+            [status, CONTENT_TYPE_JSON.merge("www-authenticate" => www_authenticate), [body.to_json]]
+          end
+
+          # Encodes a parameter value as an RFC 7230 quoted-string interior: `\` and `"` become quoted-pairs.
+          # Control characters are replaced with spaces because they cannot appear in a header value at all;
+          # leaving CR/LF in would let attacker-influenced text (e.g. an error message quoting a bad token)
+          # split the response header, and other control characters make strict servers reject the response outright.
+          # Invalid byte sequences are replaced first: a custom verifier's message need not be valid UTF-8,
+          # and `gsub` raising on it would escape the rescue that builds the challenge, turning the 401 into a 500.
+          def quote(value)
+            utf8(value).gsub(/[[:cntrl:]]/, " ").gsub(/[\\"]/) { |character| "\\#{character}" }
+          end
+
+          # Normalizes a value to valid UTF-8. `scrub` alone only repairs strings tagged UTF-8:
+          # Rack hands header values to a custom verifier as ASCII-8BIT, where every byte counts as valid,
+          # so a message assembled from them would still make `to_json` raise.
+          def utf8(value)
+            value.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module OAuth
+      # Error hierarchy for the OAuth 2.1 resource-server role. Each error carries the RFC 6750 Section 3.1
+      # registered error code that `Challenge` places in the `WWW-Authenticate` response header.
+      # https://www.rfc-editor.org/rfc/rfc6750#section-3.1
+      class Error < StandardError
+        attr_reader :error_code
+
+        # `error_code` defaults to the code a token rejection carries, so a custom verifier can subclass this
+        # and `raise MyError, "..."` without knowing about the keyword. `Authenticator#challenge_response`
+        # answers any such error with 401 `invalid_token`, which is what the default names; without a default,
+        # the missing keyword would raise `ArgumentError` inside `verify` and surface as HTTP 500 instead.
+        def initialize(message = nil, error_code: "invalid_token")
+          super(message)
+          @error_code = error_code
+        end
+      end
+
+      # The request is malformed (e.g. an `Authorization` header that does not carry a Bearer token). Maps to HTTP 400.
+      class InvalidRequestError < Error
+        def initialize(message = "The request is malformed")
+          super(message, error_code: "invalid_request")
+        end
+      end
+
+      # The access token is missing, expired, revoked, or otherwise invalid.
+      # Maps to HTTP 401. `TokenVerifier` implementations raise this to reject a token.
+      class InvalidTokenError < Error
+        def initialize(message = "The access token is invalid")
+          super(message, error_code: "invalid_token")
+        end
+      end
+
+      # The request carried no credentials at all. A subclass of `InvalidTokenError` so existing rescue clauses keep working,
+      # but distinguished because RFC 6750 Section 3.1 says the challenge answering a credential-less request should not include
+      # an error code.
+      class MissingTokenError < InvalidTokenError
+        def initialize(message = "Missing Authorization header")
+          super
+        end
+      end
+
+      # The token is valid but lacks a scope the resource requires. Maps to HTTP 403, whose `WWW-Authenticate` challenge signals
+      # step-up authorization (the scope challenge handling of the MCP authorization specification) to the client.
+      class InsufficientScopeError < Error
+        attr_reader :required_scopes
+
+        def initialize(message = "The request requires higher privileges", required_scopes: [])
+          super(message, error_code: "insufficient_scope")
+          @required_scopes = required_scopes
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/introspection_verifier.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "mcp/client/oauth/discovery"
+require_relative "token_verifier"
+
+module MCP
+  class Server
+    module OAuth
+      # Verifies access tokens by asking the authorization server via OAuth 2.0 Token Introspection (RFC 7662).
+      # Works with opaque tokens and needs no extra dependencies.
+      #
+      #   verifier = MCP::Server::OAuth::IntrospectionVerifier.new(
+      #     introspection_endpoint: "https://as.example.com/oauth/introspect",
+      #     client_id: "mcp-resource-server",
+      #     client_secret: ENV["INTROSPECTION_CLIENT_SECRET"],
+      #     resource_metadata: metadata, # the ProtectedResourceMetadata this server publishes; its `resource` is the expected `aud`
+      #   )
+      #
+      # Every `verify` call hits the endpoint; responses are intentionally not cached so token revocation takes
+      # effect within the authorization server's own latency, not ours.
+      #
+      # `audience` is required: the introspection response's `aud` (or `resource`) must cover it,
+      # which is the RFC 8707 audience check the MCP authorization specification demands of every resource server.
+      # It keeps a token issued for another resource from being replayed here. An authorization server that cannot
+      # audience-bind its tokens needs a custom verifier, and the deployment should understand what it is giving up.
+      class IntrospectionVerifier < TokenVerifier
+        # Raised when the introspection endpoint is unreachable or misbehaves. Deliberately not an `OAuth::Error`:
+        # an unavailable authorization server is an internal failure (HTTP 500), not a problem with the client's token.
+        class IntrospectionError < StandardError; end
+
+        # Named after the RFC 7591 `token_endpoint_auth_method` values, the same vocabulary the client side uses.
+        CLIENT_AUTH_METHODS = [:client_secret_basic, :client_secret_post, :none].freeze
+        private_constant :CLIENT_AUTH_METHODS
+
+        def initialize(
+          introspection_endpoint:,
+          resource_metadata:,
+          client_id: nil,
+          client_secret: nil,
+          client_auth_method: :client_secret_basic,
+          open_timeout: 5,
+          read_timeout: 5
+        )
+          super()
+
+          unless Client::OAuth::Discovery.secure_url?(introspection_endpoint)
+            raise ArgumentError, "introspection_endpoint must use https (http is allowed only on loopback): #{introspection_endpoint.inspect}"
+          end
+
+          # The RFC 8707 audience check keeps tokens issued for other resources from being replayed against this server;
+          # the expected value is the `resource` of the document this server publishes.
+          audience = resource_from(resource_metadata)
+          require_expected_claim!(:audience, audience)
+          require_positive_number!(:open_timeout, open_timeout)
+          require_positive_number!(:read_timeout, read_timeout)
+          unless CLIENT_AUTH_METHODS.include?(client_auth_method)
+            raise ArgumentError, "client_auth_method must be one of #{CLIENT_AUTH_METHODS.join(", ")}"
+          end
+          if client_auth_method != :none && client_id.nil?
+            raise ArgumentError, "client_id is required for client_auth_method #{client_auth_method.inspect}"
+          end
+
+          @introspection_endpoint = introspection_endpoint
+          @client_id = client_id
+          @client_secret = client_secret
+          @client_auth_method = client_auth_method
+          @audience = audience
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+        end
+
+        def verify(token)
+          claims = introspect(token)
+
+          raise InvalidTokenError, "Token is not active" unless claims["active"] == true
+
+          validate_audience!(claims)
+
+          access_token = access_token_from_claims(token, claims, resource: @audience)
+          # An active-but-expired introspection response would be an authorization server bug, but expiry is this verifier's contractual duty,
+          # so it is enforced here rather than trusted.
+          raise InvalidTokenError, "Token expired" if access_token.expired?
+
+          access_token
+        end
+
+        private
+
+        def introspect(token)
+          uri = URI.parse(@introspection_endpoint)
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Accept"] = "application/json"
+
+          form = { "token" => token }
+          case @client_auth_method
+          when :client_secret_basic
+            request["Authorization"] = "Basic #{basic_credentials}"
+          when :client_secret_post
+            form["client_id"] = @client_id
+            form["client_secret"] = @client_secret.to_s
+          end
+          request.set_form_data(form)
+
+          body = "".dup
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+            http.request(request) do |response|
+              unless response.is_a?(Net::HTTPOK)
+                raise IntrospectionError, "Introspection endpoint responded with status #{response.code}"
+              end
+
+              response.read_body do |chunk|
+                body << chunk
+                if body.bytesize > MAX_UPSTREAM_RESPONSE_BYTES
+                  raise IntrospectionError, "Introspection response exceeded #{MAX_UPSTREAM_RESPONSE_BYTES} bytes"
+                end
+              end
+            end
+          end
+
+          parsed = JSON.parse(body)
+          unless parsed.is_a?(Hash)
+            raise IntrospectionError, "Introspection endpoint returned a non-object JSON document"
+          end
+
+          parsed
+        rescue JSON::ParserError
+          raise IntrospectionError, "Introspection endpoint returned invalid JSON"
+        end
+
+        # RFC 6749 Section 2.3.1: the client id and secret are form-urlencoded before being joined and base64-encoded,
+        # so a `:` or another reserved character in either survives the round trip; `Net::HTTP#basic_auth` skips that step.
+        def basic_credentials
+          credentials = "#{URI.encode_www_form_component(@client_id)}:#{URI.encode_www_form_component(@client_secret.to_s)}"
+
+          [credentials].pack("m0")
+        end
+
+        def validate_audience!(claims)
+          audience_values = Array(claims["aud"]) + Array(claims["resource"])
+          return if audience_values.include?(@audience)
+
+          raise InvalidTokenError, "Invalid audience"
+        end
+      end
+    end
+  end
+end