mcp 1.7.0 → 1.8.1

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

data/lib/mcp/server/transports/stdio_transport.rb

@@ -49,10 +49,26 @@ module MCP
             end
             break if line.nil?
 
-            line = line.strip
-            parsed = parse_line(line)
-            response = parsed ? dispatch_with_era(parsed) : @session.handle_json(line)
-            send_response(response) if response
+            line = strip_frame(line)
+
+            # Reset for each frame: the loop body shares one scope, so a frame whose parse raises would otherwise
+            # be answered with the previous frame's id.
+            parsed = nil
+
+            begin
+              parsed = parse_line(line)
+              response = parsed ? dispatch_with_era(parsed) : @session.handle_json(line)
+
+              send_response(response) if response
+            rescue StandardError => e
+              # One frame must not end the connection: a reply that cannot be generated (a request string
+              # the JSON parser passed through without being valid UTF-8, echoed by the SDK or a handler) or
+              # any other failure past the server's own error handling answers that frame with Internal error,
+              # unless the frame is a notification, which gets no response.
+              MCP.configuration.exception_reporter.call(e, { error: "Failed to handle stdio frame" })
+
+              send_response(internal_error_response(parsed)) unless parsed.is_a?(Hash) && !parsed.key?(:id)
+            end
           end
         rescue Interrupt
           warn("\nExiting...")
@@ -70,6 +86,16 @@ module MCP
           $stdout.flush
         end
 
+        # The error answering a frame whose handling failed. It carries the request id when the frame was
+        # a single request whose id can be written back, and no `id` otherwise, as for an id that could not be read.
+        def internal_error_response(parsed)
+          response = { jsonrpc: JsonRpcHandler::Version::V2_0 }
+          id = parsed[:id] if parsed.is_a?(Hash)
+          response[:id] = id if id.is_a?(Integer) || (id.is_a?(String) && id.valid_encoding?)
+          response[:error] = { code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR, message: "Internal error" }
+          response
+        end
+
         def send_notification(method, params = nil)
           notification = {
             jsonrpc: "2.0",
@@ -111,8 +137,8 @@ module MCP
 
           while @open && (line = read_line($stdin))
             begin
-              parsed = JSON.parse(line.strip, symbolize_names: true)
-            rescue JSON::ParserError => e
+              parsed = JSON.parse(strip_frame(line), symbolize_names: true)
+            rescue JSON::ParserError, EncodingError => e
               MCP.configuration.exception_reporter.call(e, { error: "Failed to parse response" })
               raise
             end
@@ -152,13 +178,22 @@ module MCP
           line
         end
 
+        # Strips a frame as bytes. `$stdin` is read as UTF-8, and `String#strip` raises for a UTF-8 string holding
+        # an invalid byte at either end on every supported Ruby, and anywhere in it from Ruby 3.2 on, so one such
+        # frame would end the read loop instead of being answered. As bytes, it reaches the parser, which refuses
+        # what is not JSON with a parse error.
+        def strip_frame(line)
+          line.b.strip.force_encoding(Encoding::UTF_8)
+        end
+
         # Parses a frame once so era classification can inspect its method and `_meta`.
         # Returns `nil` for frames that are not JSON objects; those fall back to
         # `ServerSession#handle_json` so protocol-level error responses stay identical.
         def parse_line(line)
           parsed = JSON.parse(line, symbolize_names: true)
           parsed.is_a?(Hash) ? parsed : nil
-        rescue JSON::ParserError
+        rescue JSON::ParserError, EncodingError
+          # `symbolize_names` raises `EncodingError` for a key that is not valid UTF-8; `handle_json` answers the parse error.
           nil
         end
 
@@ -168,7 +203,9 @@ module MCP
         # (an `initialize` after a modern lock, a modern envelope after a legacy lock, or a missing envelope after a modern lock)
         # are rejected in-band by `Server#lift_request_envelope`.
         def dispatch_with_era(parsed)
-          response = @session.handle(parsed)
+          # Passing `auth_info:` keeps Ruby 2.7 from taking the request Hash as keyword arguments,
+          # which works but warns that the conversion is deprecated.
+          response = @session.handle(parsed, auth_info: nil)
           lock_modern_era_on_success(parsed, response)
           response
         end