mcp 1.6.1 → 1.8.0

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+require_relative "challenge"
+require_relative "errors"
+
+module MCP
+  class Server
+    module OAuth
+      # Rack middleware that enforces bearer authentication for everything it wraps, per RFC 6750 and the MCP authorization specification:
+      #
+      #   use MCP::Server::OAuth::Middleware,
+      #     token_verifier: verifier,
+      #     required_scopes: ["mcp:tools"],
+      #     resource_metadata: metadata
+      #   run transport
+      #
+      # See `Authenticator` for the option semantics; this class only adapts it to the Rack middleware calling convention.
+      # The streamable HTTP transport embeds the same authenticator via its `token_verifier:` option, so use this middleware when composition
+      # at the Rack layer is preferable (for example to share one authenticator across several apps).
+      #
+      # Tokens are accepted from the `Authorization` header only, never from a query string. On success the verified `AccessToken` is stored in
+      # `env[MCP::Server::OAuth::ENV_KEY]`, where the streamable HTTP transport picks it up and exposes it to handlers as `server_context.auth_info`.
+      #
+      # Because the middleware wraps the whole app, POST, GET (SSE), and DELETE requests are protected uniformly. Mount the metadata document outside
+      # the protected scope: it is how unauthenticated clients bootstrap. When a browser-based client is involved, run the CORS middleware before
+      # this one; otherwise its preflight OPTIONS request dies here with a 401 that the browser will not let the client see.
+      class Middleware
+        def initialize(app, token_verifier:, required_scopes: [], resource_metadata: nil, resource_metadata_url: nil, scope_matcher: nil)
+          @app = app
+          @authenticator = Authenticator.new(
+            token_verifier: token_verifier,
+            required_scopes: required_scopes,
+            resource_metadata: resource_metadata,
+            resource_metadata_url: resource_metadata_url,
+            scope_matcher: scope_matcher,
+          )
+        end
+
+        def call(env)
+          begin
+            env[ENV_KEY] = @authenticator.authenticate(env)
+          rescue Error => e
+            return @authenticator.challenge_response(e)
+          rescue => e
+            # A misbehaving verifier (e.g. an unreachable JWKS or introspection endpoint) is an internal failure: report it
+            # and answer 500 without a challenge, so the client does not discard a perfectly good token.
+            MCP.configuration.exception_reporter.call(e, { middleware: self.class.name })
+
+            return [500, { "content-type" => "application/json" }, [{ error: "server_error" }.to_json]]
+          end
+
+          # Outside the rescue on purpose: only verification is this middleware's business, and a failure in the wrapped app
+          # must reach whatever handles that app's errors, as it does with the Python SDK's bearer middleware.
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "mcp/client/oauth/discovery"
+
+module MCP
+  class Server
+    module OAuth
+      # OAuth 2.0 Protected Resource Metadata (RFC 9728) for an MCP server.
+      # The MCP authorization spec requires servers to publish this document so clients can discover which authorization servers can
+      # issue tokens for the resource.
+      #
+      # - `resource` - the canonical resource identifier: the URL clients connect to, without a fragment. Clients send this back to
+      #   the authorization server as the RFC 8707 `resource` parameter.
+      # - `authorization_servers` - issuer URLs of the authorization servers that protect this resource (at least one).
+      # - `scopes_supported` - an Array of the scope strings clients may request (also the default scope hint in `WWW-Authenticate` challenges);
+      #   `offline_access` is dropped, and a result with nothing left omits the member.
+      # - `bearer_methods_supported` - defaults to `["header"]`: the SDK accepts bearer tokens only in the `Authorization` header,
+      #   never in a query string.
+      # - `extra` - additional RFC 9728 fields (e.g. `jwks_uri`, `resource_signing_alg_values_supported`, `resource_policy_uri`) merged into
+      #   the document as given; the members above cannot be overridden through it.
+      #
+      # https://www.rfc-editor.org/rfc/rfc9728
+      # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery
+      class ProtectedResourceMetadata
+        WELL_KNOWN_PATH_PREFIX = "/.well-known/oauth-protected-resource"
+
+        DEFAULT_BEARER_METHODS_SUPPORTED = ["header"].freeze
+        private_constant :DEFAULT_BEARER_METHODS_SUPPORTED
+
+        # The members `initialize` validates. `extra` may not name them, or the merge in `to_h` would undo the validation.
+        VALIDATED_MEMBERS = ["resource", "authorization_servers", "scopes_supported", "resource_name", "resource_documentation", "bearer_methods_supported"].freeze
+        private_constant :VALIDATED_MEMBERS
+
+        attr_reader :resource, :authorization_servers, :scopes_supported, :resource_name, :resource_documentation, :bearer_methods_supported, :extra
+
+        def initialize(resource:, authorization_servers:, scopes_supported: nil, resource_name: nil, resource_documentation: nil, bearer_methods_supported: DEFAULT_BEARER_METHODS_SUPPORTED, extra: {})
+          @resource_uri = parse_resource_uri(resource)
+          @resource = resource
+
+          servers = Array(authorization_servers)
+          raise ArgumentError, "authorization_servers must contain at least one issuer URL" if servers.empty?
+
+          servers.each do |server|
+            next if Client::OAuth::Discovery.secure_url?(server)
+
+            raise ArgumentError, "authorization_servers must use https (http is allowed only on loopback): #{server.inspect}"
+          end
+
+          overridden = extra.keys.map(&:to_s) & VALIDATED_MEMBERS
+          unless overridden.empty?
+            raise ArgumentError, "extra must not override #{overridden.join(", ")}; pass them as keyword arguments so they are validated"
+          end
+
+          @authorization_servers = servers
+          @scopes_supported = advertisable_scopes(scopes_supported)
+          @resource_name = resource_name
+          @resource_documentation = resource_documentation
+          @bearer_methods_supported = bearer_methods_supported
+          @extra = extra
+        end
+
+        def to_h
+          {
+            resource: resource,
+            authorization_servers: authorization_servers,
+            scopes_supported: scopes_supported,
+            resource_name: resource_name,
+            resource_documentation: resource_documentation,
+            bearer_methods_supported: bearer_methods_supported,
+          }.compact.merge(extra)
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+
+        # The path-inserted well-known path per RFC 9728 Section 3: a resource of `https://example.com/mcp` is described at
+        # `/.well-known/oauth-protected-resource/mcp`, and a resource at the origin root is described at `/.well-known/oauth-protected-resource`.
+        # The path math intentionally matches what `MCP::Client::OAuth::Discovery.protected_resource_metadata_urls` probes.
+        def well_known_path
+          path = @resource_uri.path
+          path = "" if path == "/"
+
+          "#{WELL_KNOWN_PATH_PREFIX}#{path}"
+        end
+
+        # The absolute URL of the metadata document. Pass this to `Middleware` (or `Challenge`) as `resource_metadata_url` so 401/403 challenges point
+        # clients at the document.
+        def well_known_url
+          port = @resource_uri.port && @resource_uri.port != @resource_uri.default_port ? ":#{@resource_uri.port}" : ""
+
+          "#{@resource_uri.scheme}://#{@resource_uri.host}#{port}#{well_known_path}"
+        end
+
+        private
+
+        # The MCP authorization specification tells protected resources not to advertise `offline_access`: refresh token issuance
+        # is the authorization server's business, not a resource requirement. `Authenticator` already drops it from the `scope` parameter of
+        # a `WWW-Authenticate` challenge, so dropping it here keeps the document and the challenges saying the same thing.
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+        # Nothing left to advertise drops the member from the document instead of emitting `[]`, which RFC 9728 tells servers to omit,
+        # and a non-Array is refused because a bare String would be ambiguous between one scope and a list.
+        def advertisable_scopes(scopes_supported)
+          return if scopes_supported.nil?
+          raise ArgumentError, "scopes_supported must be an Array of scope strings" unless scopes_supported.is_a?(Array)
+
+          scopes = scopes_supported.map(&:to_s) - ["offline_access"]
+
+          scopes.empty? ? nil : scopes
+        end
+
+        def parse_resource_uri(resource)
+          uri = begin
+            URI.parse(resource.to_s)
+          rescue URI::InvalidURIError
+            raise ArgumentError, "resource must be a valid URI: #{resource.inspect}"
+          end
+
+          unless ["http", "https"].include?(uri.scheme.to_s.downcase) && uri.host && !uri.host.empty?
+            raise ArgumentError, "resource must be an absolute http(s) URL: #{resource.inspect}"
+          end
+
+          if uri.fragment
+            raise ArgumentError, "resource must not contain a fragment per RFC 8707: #{resource.inspect}"
+          end
+
+          unless Client::OAuth::Discovery.secure_url?(resource.to_s)
+            raise ArgumentError, "resource must use https (http is allowed only on loopback): #{resource.inspect}"
+          end
+
+          uri
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MCP
+  class Server
+    module OAuth
+      # Rack middleware that serves a Protected Resource Metadata document (RFC 9728) at its well-known path,
+      # with the CORS headers browser-based MCP clients need, and passes every other request down the stack.
+      # The Rack shape of the Python SDK's `create_protected_resource_routes` and the TypeScript SDK's `mcpAuthMetadataRouter`.
+      #
+      # Use it at the top of the stack: the well-known path lives at the origin root, not under the MCP endpoint
+      # (`/.well-known/oauth-protected-resource/mcp` for a resource at `/mcp`), so inside a `map` block it would never see that path.
+      # The metadata is how unauthenticated clients bootstrap, so it belongs above any bearer enforcement.
+      #
+      #   metadata = MCP::Server::OAuth::ProtectedResourceMetadata.new(...)
+      #   use MCP::Server::OAuth::ProtectedResourceMetadataMiddleware, metadata
+      #   map("/mcp") { run(transport) }
+      class ProtectedResourceMetadataMiddleware
+        ALLOWED_METHODS = "GET, HEAD, OPTIONS"
+        private_constant :ALLOWED_METHODS
+
+        # @param app [#call] the rest of the Rack stack
+        # @param metadata [ProtectedResourceMetadata] the document to serve, which also names the path it is served at
+        def initialize(app, metadata)
+          # The document is published as `to_json`, so only the class whose serialization is a validated RFC 9728 document will do.
+          unless metadata.is_a?(ProtectedResourceMetadata)
+            raise ArgumentError, "metadata must be a ProtectedResourceMetadata (got #{metadata.class})"
+          end
+
+          @app = app
+          @well_known_path = metadata.well_known_path
+          @metadata_json = metadata.to_json
+        end
+
+        def call(env)
+          # An exact match only: a deeper well-known path describes another resource on this host (RFC 9728),
+          # and every other path is the application's.
+          return @app.call(env) unless env["PATH_INFO"] == @well_known_path
+
+          case env["REQUEST_METHOD"]
+          when "GET"
+            metadata_response
+          when "HEAD"
+            metadata_response(head: true)
+          when "OPTIONS"
+            preflight_response
+          else
+            method_not_allowed_response
+          end
+        end
+
+        private
+
+        def metadata_response(head: false)
+          headers = {
+            "content-type" => "application/json",
+            "cache-control" => "public, max-age=3600",
+            "access-control-allow-origin" => "*",
+          }
+
+          [200, headers, head ? [] : [@metadata_json]]
+        end
+
+        def preflight_response
+          headers = {
+            "access-control-allow-origin" => "*",
+            "access-control-allow-methods" => ALLOWED_METHODS,
+            "access-control-allow-headers" => "*",
+          }
+
+          [204, headers, []]
+        end
+
+        def method_not_allowed_response
+          headers = {
+            "content-type" => "application/json",
+            "allow" => ALLOWED_METHODS,
+          }
+
+          [405, headers, [{ error: "method_not_allowed" }.to_json]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "access_token"
+require_relative "errors"
+
+module MCP
+  class Server
+    module OAuth
+      # The single integration point of the resource-server role: token in, `AccessToken` out. `Authenticator` accepts any object
+      # that responds to `verify(token)`, so subclassing is optional; this base class documents the contract and shares the claim mapping
+      # used by the built-in verifiers.
+      #
+      # Implementations MUST raise `InvalidTokenError` when the token is invalid, and that includes an expired token: expiry enforcement
+      # is part of this contract, not something the caller re-checks (the built-in verifiers honor their configured clock leeway when doing so).
+      # Returning nil is also treated as a rejection by `Authenticator`, with a generic message. Any other exception is treated as
+      # an internal error (HTTP 500), not as a client failure.
+      #
+      # Error messages are echoed into the `WWW-Authenticate` response header, so they must never contain token material or other secrets.
+      class TokenVerifier
+        # Upper bound for response bodies read from authorization-server endpoints (JWKS, introspection). Matches the bound the client-side
+        # OAuth support applies to authorization-server responses; the documents involved are orders of magnitude smaller.
+        MAX_UPSTREAM_RESPONSE_BYTES = 4 * 1024 * 1024
+
+        # @param token [String] the raw bearer token from the `Authorization` header
+        # @return [AccessToken]
+        # @raise [InvalidTokenError] when the token is invalid, expired, or not meant for this resource
+        def verify(token)
+          raise NotImplementedError, "#{self.class.name}#verify is not implemented"
+        end
+
+        private
+
+        # Guards an expected `iss` or `aud` value at construction. The built-in verifiers compare tokens against these values,
+        # and a nil or empty expectation would silently turn the comparison off (the jwt gem skips a check whose expected value is nil),
+        # so a misconfiguration such as an unset environment variable fails loudly instead.
+        def require_expected_claim!(name, value)
+          return if value.is_a?(String) && !value.empty?
+
+          claim = name == :issuer ? "iss" : "aud"
+
+          raise ArgumentError, "#{name} must be a non-empty String (got #{value.inspect}); without it the #{claim} check would be skipped"
+        end
+
+        # The expected `aud` is the RFC 9728 document's `resource`: the canonical URL tokens are issued for, and the one this server publishes,
+        # so the verifier cannot drift from it.
+        def resource_from(resource_metadata)
+          metadata_member(resource_metadata, :resource)
+        end
+
+        # The expected `iss` comes from the document as well: its authorization servers are issuer identifiers (RFC 9728),
+        # and a JWT verifier holds one key set, so it verifies the tokens of exactly one of them. A document naming several
+        # would advertise an authorization server whose tokens this verifier rejects, so it is refused outright.
+        def issuer_from(resource_metadata)
+          servers = metadata_member(resource_metadata, :authorization_servers)
+          return servers.first if servers.one?
+
+          raise ArgumentError, <<~MESSAGE
+            JWTVerifier verifies the tokens of one authorization server, and resource_metadata names \
+            #{servers.size}; publish one, or verify with a custom verifier that holds each issuer's keys
+          MESSAGE
+        end
+
+        # A document standing in for `ProtectedResourceMetadata` must still hand over the shapes that class guarantees,
+        # so a wrong one fails here with a named member rather than deeper in with a `NoMethodError`.
+        def metadata_member(resource_metadata, name)
+          unless resource_metadata.respond_to?(name)
+            raise ArgumentError, "resource_metadata must be a ProtectedResourceMetadata (got #{resource_metadata.class})"
+          end
+
+          value = resource_metadata.public_send(name)
+          shape = name == :resource ? "a String" : "an Array of Strings"
+          valid = name == :resource ? value.is_a?(String) : value.is_a?(Array) && value.all?(String)
+          raise ArgumentError, "resource_metadata.#{name} must be #{shape} (got #{value.inspect})" unless valid
+
+          value
+        end
+
+        # Maps a string-keyed claims Hash (JWT payload or RFC 7662 introspection response; the relevant claim names are identical) to an `AccessToken`.
+        def access_token_from_claims(token, claims, resource: nil)
+          AccessToken.new(
+            token: token,
+            client_id: claims["client_id"] || claims["azp"],
+            scopes: scopes_from_claims(claims),
+            expires_at: expiry_from_claims(claims),
+            subject: claims["sub"],
+            issuer: claims["iss"],
+            audience: claims["aud"],
+            resource: resource,
+            claims: claims,
+          )
+        end
+
+        # RFC 8693 style `scope` is a space-delimited string, but some authorization servers emit an array of scope strings instead.
+        def scopes_from_claims(claims)
+          scope = claims["scope"]
+
+          scope.is_a?(Array) ? scope.map(&:to_s) : scope.to_s.split
+        end
+
+        # `exp` is a numeric timestamp in a JWT payload and in an introspection response alike, but a lenient authorization server may emit it as
+        # a numeric string. Any other shape is rejected as an invalid token: passed through, it would make `AccessToken#expired?` raise on comparison
+        # and turn a malformed upstream response into an internal error.
+        def expiry_from_claims(claims)
+          exp = claims["exp"]
+
+          case exp
+          when nil
+            nil
+          when Numeric
+            # JSON parses `1e1000` to Infinity, whose `to_i` raises.
+            raise InvalidTokenError, "Malformed exp claim" unless exp.finite?
+
+            exp.to_i
+          when /\A\d+\z/
+            exp.to_i
+          else
+            raise InvalidTokenError, "Malformed exp claim"
+          end
+        end
+
+        def require_non_negative_number!(name, value)
+          return if value.is_a?(Numeric) && value.finite? && value >= 0
+
+          raise ArgumentError, "#{name} must be a non-negative finite number (got #{value.inspect})"
+        end
+
+        def require_positive_number!(name, value)
+          return if value.is_a?(Numeric) && value.finite? && value.positive?
+
+          raise ArgumentError, "#{name} must be a positive finite number (got #{value.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "oauth/errors"
+
+module MCP
+  class Server
+    # OAuth 2.1 resource-server support per the MCP authorization specification: bearer token verification,
+    # Protected Resource Metadata (RFC 9728) serving, and RFC 6750 `WWW-Authenticate` challenges.
+    # The MCP server never acts as an authorization server; token issuance belongs to an external provider.
+    # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+    module OAuth
+      # The Rack env key under which the transport's built-in enforcement and `Middleware` store
+      # the verified `AccessToken`. The streamable HTTP transport reads this key and threads the value through
+      # to handlers as `server_context.auth_info`. Custom integrations that verify tokens themselves can set
+      # the same key to opt in to that propagation.
+      ENV_KEY = "mcp.auth_info"
+
+      autoload :AccessToken, "mcp/server/oauth/access_token"
+      autoload :Authenticator, "mcp/server/oauth/authenticator"
+      autoload :Challenge, "mcp/server/oauth/challenge"
+      autoload :IntrospectionVerifier, "mcp/server/oauth/introspection_verifier"
+      autoload :JWTVerifier, "mcp/server/oauth/jwt_verifier"
+      autoload :Middleware, "mcp/server/oauth/middleware"
+      autoload :ProtectedResourceMetadata, "mcp/server/oauth/protected_resource_metadata"
+      autoload :ProtectedResourceMetadataMiddleware, "mcp/server/oauth/protected_resource_metadata_middleware"
+      autoload :TokenVerifier, "mcp/server/oauth/token_verifier"
+    end
+  end
+end