mcp 0.23.0 → 0.25.0

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # OAuth client configuration for the MCP Enterprise Managed Authorization extension (SEP-990, "Cross-App Access"):
+      # the client obtains an Identity Assertion Authorization Grant (ID-JAG) from an enterprise identity provider and
+      # presents it to the MCP authorization server with the RFC 7523 `jwt-bearer` grant, authenticating with
+      # `client_secret_basic`. Handed to `MCP::Client::HTTP` via the `oauth:` keyword, the same as `Provider`.
+      #
+      # Mirrors `CrossAppAccessProvider` in the TypeScript SDK: the assertion is supplied by a callable so it can come
+      # from `IDJAGTokenExchange` (the common case), an enterprise secret store, or a test double.
+      #
+      # Required keyword arguments:
+      #
+      # - `client_id`     - String identifying the pre-registered confidential client at the MCP authorization server.
+      # - `client_secret` - String shared secret for `client_secret_basic`.
+      # - `assertion_provider` - Callable invoked as `call(audience:, resource:)`, returning the ID-JAG assertion to
+      #   present. `audience` is the authorization server's issuer identifier and `resource` is the canonical MCP server URL;
+      #   pass both through to `IDJAGTokenExchange.request` when exchanging an IdP ID token.
+      #
+      # Optional keyword arguments:
+      #
+      # - `scope`   - String of space-separated scopes to request when the server's `WWW-Authenticate` and
+      #   the Protected Resource Metadata do not specify one.
+      # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`.
+      #   Defaults to an `InMemoryStorage`.
+      #
+      # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
+      class CrossAppAccessProvider
+        include StorageBackedProvider
+
+        # Raised when the provider is constructed without the pieces the `jwt-bearer` grant needs.
+        class InvalidConfigurationError < ArgumentError; end
+
+        attr_reader :scope, :storage
+
+        def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil)
+          if blank?(client_id)
+            raise InvalidConfigurationError, "client_id is required for the jwt-bearer grant."
+          end
+
+          if blank?(client_secret)
+            raise InvalidConfigurationError, "client_secret is required: SEP-990 authenticates the jwt-bearer grant with client_secret_basic."
+          end
+
+          unless assertion_provider.respond_to?(:call)
+            raise InvalidConfigurationError, "assertion_provider must be callable as `call(audience:, resource:)` and return the ID-JAG assertion."
+          end
+
+          @assertion_provider = assertion_provider
+          @scope = scope
+          @storage = storage || InMemoryStorage.new
+          @storage.save_client_information(
+            "client_id" => client_id,
+            "client_secret" => client_secret,
+            "token_endpoint_auth_method" => "client_secret_basic",
+          )
+        end
+
+        # See `Provider#authorization_flow`.
+        def authorization_flow
+          :jwt_bearer
+        end
+
+        # Returns the ID-JAG assertion to present at the MCP authorization server. Called by `Flow#run_jwt_bearer!` with the audience
+        # and resource resolved during discovery.
+        def jwt_bearer_assertion(audience:, resource:)
+          @assertion_provider.call(audience: audience, resource: resource)
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

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

@@ -37,7 +37,7 @@ module MCP
         # Matches a single `key=value` pair inside an HTTP auth-scheme challenge.
         # `value` is either a quoted string (which can contain commas and spaces)
         # or a bare token, per RFC 7235.
-        WWW_AUTH_PARAM_PATTERN = /\A([A-Za-z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/
+        WWW_AUTH_PARAM_PATTERN = /\A([A-Za-z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/.freeze
 
         class << self
           # Parses a `WWW-Authenticate` header and returns the parameters of

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

@@ -51,8 +51,11 @@ module MCP
 
           as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
 
-          if provider_authorization_flow == :client_credentials
+          case provider_authorization_flow
+          when :client_credentials
             return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
+          when :jwt_bearer
+            return run_jwt_bearer!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
           end
 
           ensure_pkce_supported!(as_metadata)
@@ -74,13 +77,20 @@ module MCP
           )
 
           @provider.redirect_handler.call(authorization_url)
-          code, returned_state = Array(@provider.callback_handler.call)
+          callback_result = Array(@provider.callback_handler.call)
+          code, returned_state, returned_iss = callback_result
           raise AuthorizationError, "Authorization callback did not return an authorization code." unless code
 
           unless states_match?(returned_state, state)
             raise AuthorizationError, "OAuth state mismatch (CSRF protection)."
           end
 
+          validate_authorization_response_issuer!(
+            as_metadata: as_metadata,
+            iss: returned_iss,
+            iss_provided: callback_result.length >= 3,
+          )
+
           tokens = exchange_authorization_code(
             as_metadata: as_metadata,
             client_info: client_info,
@@ -101,6 +111,7 @@ module MCP
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
         def run_client_credentials!(as_metadata:, prm:, resource:, scope:)
           client_info = client_credentials_client_info
+          ensure_client_credentials_issuer!(client_info, as_metadata: as_metadata)
 
           form = { "grant_type" => "client_credentials" }
           effective_scope = resolve_scope(scope: scope, prm: prm)
@@ -127,6 +138,55 @@ module MCP
           info
         end
 
+        # Per SEP-2352, static machine-to-machine credentials are bound to their authorization
+        # server the same way registered ones are: when the stored `client_information` records
+        # an `issuer` that differs from the current authorization server, surface an error
+        # instead of silently sending another server's credentials (the spec's "SHOULD surface
+        # an error"; the TypeScript SDK raises `AuthorizationServerMismatchError` here).
+        # Re-registration is not an option for the `client_credentials` grant - the credentials
+        # are pre-registered, not DCR results - so the operator must update the stored credentials.
+        # Credentials without a recorded issuer keep working unchanged.
+        def ensure_client_credentials_issuer!(client_info, as_metadata:)
+          stored_issuer = client_info_required_value(client_info, "issuer")
+          return if stored_issuer.nil?
+          return if stored_issuer == as_metadata["issuer"]
+
+          raise AuthorizationError,
+            "Stored client credentials are bound to a different authorization server " \
+              "(stored issuer #{stored_issuer.inspect}, current #{as_metadata["issuer"].inspect}); " \
+              "refusing to send them to the current authorization server (SEP-2352)."
+        end
+
+        # Runs the RFC 7523 `jwt-bearer` grant for the SEP-990 Enterprise Managed Authorization extension:
+        # the provider supplies an ID-JAG assertion (typically obtained from an enterprise IdP via `IDJAGTokenExchange`),
+        # which is presented at the token endpoint with `client_secret_basic` authentication. Shares the same discovery
+        # and security checks as `run!`; like `client_credentials`, there is no PKCE, redirect, or authorization request.
+        # The assertion's audience is the issuer identifier that `ensure_issuer_matches!` validated.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
+        def run_jwt_bearer!(as_metadata:, prm:, resource:, scope:)
+          client_info = @provider.client_information
+          unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
+            raise AuthorizationError, "Cannot run the jwt-bearer grant: the provider has no stored `client_id`."
+          end
+
+          assertion = @provider.jwt_bearer_assertion(audience: as_metadata["issuer"], resource: resource)
+          if assertion.nil? || assertion.to_s.empty?
+            raise AuthorizationError, "The provider's assertion_provider returned no ID-JAG assertion."
+          end
+
+          form = {
+            "grant_type" => "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            "assertion" => assertion,
+          }
+          effective_scope = resolve_scope(scope: scope, prm: prm)
+          form["scope"] = effective_scope if effective_scope
+          form["resource"] = resource if resource
+
+          tokens = post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
+          @provider.save_tokens(tokens)
+          :authorized
+        end
+
         # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749 Section 6).
         # Re-discovers PRM and AS metadata so we always pick up a moved token endpoint, and re-runs the audience / issuer / security
         # checks before talking to it.
@@ -166,6 +226,7 @@ module MCP
           client_info = if have_stored_client_info
             # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
             # do not silently swap it for the CIMD URL even when the AS also advertises CIMD support.
+            ensure_refreshable_client_information!(stored_client_info, as_metadata: as_metadata)
             stored_client_info
           elsif as_metadata["client_id_metadata_document_supported"] == true
             { "client_id" => @provider.client_id_metadata_document_url }
@@ -412,8 +473,8 @@ module MCP
         end
 
         def ensure_client_registered(as_metadata:)
-          existing = @provider.client_information
-          return existing if existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
+          existing = stored_client_information_for(issuer: as_metadata["issuer"])
+          return existing if existing
 
           # Per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`,
           # if the authorization server advertises Client ID Metadata Document support and the provider has
@@ -462,7 +523,12 @@ module MCP
               "Dynamic client registration response is missing `client_id`."
           end
 
-          @provider.save_client_information(info)
+          # Per SEP-2352, persisted client credentials are keyed by the issuer identifier of
+          # the authorization server that minted them, so a later flow can detect an AS change and
+          # re-register instead of replaying another server's credentials. `issuer` is not an RFC 7591 response field;
+          # the SDK adds it to the opaque persisted hash.
+          @provider.save_client_information(info.merge("issuer" => as_metadata["issuer"]))
+
           info
         end
 
@@ -480,6 +546,60 @@ module MCP
           metadata.merge("application_type" => Discovery.infer_application_type(redirect_uris))
         end
 
+        # Returns the stored `client_information` when it may be used against the authorization server
+        # identified by `issuer`, applying SEP-2352's authorization server binding rules:
+        #
+        # - Credentials persisted with an `"issuer"` binding MUST NOT be reused against
+        #   a different authorization server. When the AS changed, the stale registration and its tokens
+        #   are discarded (tokens minted by the old AS are dead at the new one) and nil is returned so
+        #   the flow re-registers.
+        # - Stored credentials without an `"issuer"` binding (data persisted by an older SDK version,
+        #   or user-supplied pre-registered credentials) are bound to the current issuer on first use.
+        # - A CIMD `client_id` (an HTTPS URL) is portable across authorization servers, so it is reused
+        #   and re-bound instead of discarded.
+        #
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2352
+        def stored_client_information_for(issuer:)
+          existing = @provider.client_information
+          return unless existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
+
+          stored_issuer = client_info_required_value(existing, "issuer")
+          return existing if stored_issuer == issuer
+          return rebind_client_information(existing, issuer: issuer) if stored_issuer.nil?
+
+          client_id = client_info_required_value(existing, "client_id")
+          return rebind_client_information(existing, issuer: issuer) if Discovery.client_id_metadata_document_url?(client_id)
+
+          @provider.save_client_information(nil)
+          @provider.clear_tokens!
+          nil
+        end
+
+        def rebind_client_information(info, issuer:)
+          rebound = info.merge("issuer" => issuer)
+          @provider.save_client_information(rebound)
+          rebound
+        end
+
+        # Per SEP-2352, stored client credentials are bound to the authorization server that issued them;
+        # refuse to replay another AS's credentials at this token endpoint. `HTTP#attempt_refresh` rescues
+        # the error and falls back to the full flow, which discards the stale registration and re-registers.
+        # Credentials without an `"issuer"` binding predate this check and are allowed through;
+        # CIMD `client_id`s are portable.
+        def ensure_refreshable_client_information!(client_info, as_metadata:)
+          stored_issuer = client_info_required_value(client_info, "issuer")
+          return if stored_issuer.nil?
+          return if stored_issuer == as_metadata["issuer"]
+
+          client_id = client_info_required_value(client_info, "client_id")
+          return if Discovery.client_id_metadata_document_url?(client_id)
+
+          raise AuthorizationError,
+            "Cannot refresh: stored client credentials were issued by a different authorization server " \
+              "(stored issuer #{stored_issuer.inspect}, current #{as_metadata["issuer"].inspect}); " \
+              "re-registration is required (SEP-2352)."
+        end
+
         # Reads `key` from a `client_information` hash that may use either string or
         # symbol keys, so users can persist the result of `JSON.parse` *or* a hand-built
         # `{ client_id:, client_secret: }` and have both work.
@@ -534,6 +654,43 @@ module MCP
           raise AuthorizationError, "#{label} #{url.inspect} is not a valid URI: #{e.message}."
         end
 
+        # Validates the RFC 9207 `iss` authorization response parameter against the issuer of the authorization server
+        # the flow is talking to, per SEP-2468 (mix-up attack mitigation in multi-IdP setups):
+        #
+        # - When the callback supplied a non-empty `iss`, it MUST equal the AS metadata `issuer` exactly (simple string comparison,
+        #   no normalization, per RFC 9207 Section 2.4); on mismatch the flow aborts before the authorization code is ever sent to
+        #   a token endpoint.
+        # - When the callback returned a 3-element `[code, state, iss]` whose `iss` is nil (asserting it inspected the authorization response
+        #   and found no `iss`) and the AS metadata advertises `authorization_response_iss_parameter_supported: true`, the missing parameter
+        #   is treated as an attack per RFC 9207 Section 2.4 and the flow aborts.
+        # - A legacy 2-element `[code, state]` callback skips the check: the caller never looked for `iss`, so its absence carries no signal.
+        #
+        # `as_metadata["issuer"]` has already been byte-compared against the discovery URL by `ensure_issuer_matches!`,
+        #  so it is the RFC 9207 anchor value. `iss` is not a secret; a plain `==` suffices.
+        #
+        # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2468
+        # - https://www.rfc-editor.org/rfc/rfc9207
+        def validate_authorization_response_issuer!(as_metadata:, iss:, iss_provided:)
+          expected = as_metadata["issuer"]
+
+          if iss && !iss.to_s.empty?
+            return if iss.to_s == expected.to_s
+
+            raise AuthorizationError,
+              "Authorization response `iss` does not match the authorization server issuer " \
+                "(expected #{expected.inspect}, got #{iss.inspect}) (RFC 9207); " \
+                "refusing to exchange the authorization code."
+          end
+
+          return unless iss_provided
+          return unless as_metadata["authorization_response_iss_parameter_supported"] == true
+
+          raise AuthorizationError,
+            "Authorization server advertises `authorization_response_iss_parameter_supported` but " \
+              "the authorization response carried no `iss` parameter (RFC 9207 Section 2.4); " \
+              "refusing to exchange the authorization code."
+        end
+
         # Constant-time comparison for the OAuth `state` parameter to prevent timing-based discovery
         # of the expected value.
         # `OpenSSL.fixed_length_secure_compare` would be ideal, but it is not available on Ruby 2.7
@@ -681,7 +838,26 @@ module MCP
           client_secret = client_info_required_value(client_info, "client_secret")
           token_endpoint_auth_method = client_info_value(client_info, "token_endpoint_auth_method")
 
-          form = form.merge("client_id" => client_id)
+          form = if token_endpoint_auth_method == "private_key_jwt"
+            # RFC 7523 Section 2.2 JWT client assertion for the `private_key_jwt` method of
+            # the `io.modelcontextprotocol/oauth-client-credentials` extension (SEP-1046).
+            # The client identity travels in the assertion's `iss`/`sub` claims, so `client_id` is
+            # omitted from the body per RFC 7521 Section 4.2 (the `client_assertion` conveys the client identity).
+            # The audience is the issuer identifier that `ensure_issuer_matches!` already byte-validated.
+            unless @provider.respond_to?(:client_assertion)
+              raise AuthorizationError,
+                "token_endpoint_auth_method is private_key_jwt but the provider does not " \
+                  "implement `client_assertion(audience:)`."
+            end
+
+            form.merge(
+              "client_assertion_type" => JWTClientAssertion::ASSERTION_TYPE,
+              "client_assertion" => @provider.client_assertion(audience: as_metadata["issuer"]),
+            )
+          else
+            form.merge("client_id" => client_id)
+          end
+
           headers = {}
           if client_secret
             case token_endpoint_auth_method

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module MCP
+  class Client
+    module OAuth
+      # RFC 8693 token exchange against an enterprise identity provider, turning an IdP-issued ID token into
+      # an Identity Assertion Authorization Grant (ID-JAG) per the MCP Enterprise Managed Authorization extension (SEP-990).
+      # The returned ID-JAG is an opaque assertion the client then presents to the MCP authorization server with
+      # the RFC 7523 `jwt-bearer` grant (see `CrossAppAccessProvider`).
+      # Mirrors `requestJwtAuthorizationGrant` in the TypeScript SDK.
+      #
+      # - https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
+      # - https://www.rfc-editor.org/rfc/rfc8693
+      module IDJAGTokenExchange
+        # Raised when the identity provider's token exchange fails or returns something other than an ID-JAG.
+        class ExchangeError < StandardError; end
+
+        GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"
+        ID_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id_token"
+        ID_JAG_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:id-jag"
+
+        class << self
+          # Exchanges `id_token` for an ID-JAG at the IdP's token endpoint and returns the assertion string.
+          #
+          # @param token_endpoint [String] The identity provider's token endpoint.
+          # @param id_token [String] The IdP-issued ID token (the subject token).
+          # @param client_id [String] The client's identifier at the IdP.
+          # @param audience [String] The MCP authorization server's issuer identifier.
+          # @param resource [String] The canonical MCP server URL (RFC 8707).
+          # @param http_client [Object, nil] Faraday-compatible client; built lazily by default.
+          def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
+            http_client ||= default_http_client
+
+            response = begin
+              http_client.post(token_endpoint) do |req|
+                req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+                req.headers["Accept"] = "application/json"
+                req.body = URI.encode_www_form(
+                  "grant_type" => GRANT_TYPE,
+                  "subject_token" => id_token,
+                  "subject_token_type" => ID_TOKEN_TYPE,
+                  "requested_token_type" => ID_JAG_TOKEN_TYPE,
+                  "audience" => audience,
+                  "resource" => resource,
+                  "client_id" => client_id,
+                )
+              end
+            rescue Faraday::Error => e
+              raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
+            end
+
+            if response.status < 200 || response.status >= 300
+              raise ExchangeError, "Identity provider token exchange returned status #{response.status}."
+            end
+
+            parse_id_jag(response)
+          end
+
+          private
+
+          def parse_id_jag(response)
+            body = response.body.is_a?(String) ? response.body : response.body.to_s
+            parsed = begin
+              JSON.parse(body)
+            rescue JSON::ParserError => e
+              raise ExchangeError, "Failed to parse token exchange response: #{e.message}."
+            end
+
+            unless parsed.is_a?(Hash)
+              raise ExchangeError, "Token exchange response is not a JSON object (got #{parsed.class})."
+            end
+
+            issued_token_type = parsed["issued_token_type"]
+            unless issued_token_type == ID_JAG_TOKEN_TYPE
+              raise ExchangeError,
+                "Token exchange did not issue an ID-JAG " \
+                  "(expected issued_token_type #{ID_JAG_TOKEN_TYPE.inspect}, got #{issued_token_type.inspect})."
+            end
+
+            assertion = parsed["access_token"]
+            if assertion.nil? || assertion.to_s.empty?
+              raise ExchangeError, "Token exchange response is missing `access_token`."
+            end
+
+            assertion
+          end
+
+          def default_http_client
+            require "faraday"
+            Faraday.new do |faraday|
+              faraday.headers["Accept"] = "application/json"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,7 +12,9 @@ module MCP
       # - `client_information`: the hash returned by Dynamic Client Registration
       #   or supplied as pre-registered credentials
       #   (`client_id`, optional `client_secret`, optional
-      #   `token_endpoint_auth_method`).
+      #   `token_endpoint_auth_method`). The SDK additionally stamps an `"issuer"` member
+      #   binding the credentials to the authorization server that issued them (SEP-2352);
+      #   custom storages should treat the hash as opaque and persist it as-is.
       #
       # This class keeps everything in process memory, so the credentials live
       # only for the lifetime of the Ruby process. Applications that need

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "securerandom"
+
+module MCP
+  class Client
+    module OAuth
+      # Builds RFC 7523 Section 2.2 JWT client assertions for the `private_key_jwt`
+      # client authentication method used by the `client_credentials` grant
+      # (MCP extension `io.modelcontextprotocol/oauth-client-credentials`, SEP-1046).
+      #
+      # The JWS is assembled with openssl so the SDK stays free of a JWT gem dependency
+      # (the TypeScript and Python SDKs use jose and PyJWT for the same assertion).
+      # Claims follow SEP-1046 and RFC 7523: `iss` and `sub` carry the client_id,
+      # `aud` carries the authorization server's issuer identifier, plus `exp`, `iat`,
+      # and a unique `jti`.
+      #
+      # - https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1046
+      # - https://www.rfc-editor.org/rfc/rfc7523#section-2.2
+      module JWTClientAssertion
+        # Raised when `signing_algorithm` is not supported.
+        class UnsupportedAlgorithmError < ArgumentError; end
+
+        # Raised when the private key cannot be parsed or does not match
+        # the requested signing algorithm (e.g. an RSA key with ES256).
+        class InvalidKeyError < ArgumentError; end
+
+        # RFC 7523 Section 2.2 `client_assertion_type` value.
+        ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+        # Assertion lifetime in seconds; matches the TypeScript SDK's `jwtLifetimeSeconds`
+        # and the Python SDK's `lifetime_seconds` default.
+        DEFAULT_LIFETIME = 300
+
+        # ES256 produces a raw `r || s` JWS signature of two 32-byte integers.
+        ES256_COMPONENT_BYTES = 32
+        private_constant :ES256_COMPONENT_BYTES
+
+        SUPPORTED_ALGORITHMS = ["ES256", "RS256"].freeze
+
+        class << self
+          # Returns a signed compact-serialization JWT (`header.payload.signature`).
+          #
+          # @param client_id [String] The pre-registered OAuth client identifier.
+          # @param audience [String] The authorization server's issuer identifier.
+          # @param private_key [String, OpenSSL::PKey::PKey] PEM string (PKCS#8 or
+          #   traditional encoding) or an already-parsed key.
+          # @param signing_algorithm [String] `"ES256"` (prime256v1 EC key) or
+          #   `"RS256"` (RSA key).
+          # @param lifetime [Integer] Seconds until the `exp` claim expires.
+          def generate(client_id:, audience:, private_key:, signing_algorithm:, lifetime: DEFAULT_LIFETIME)
+            unless SUPPORTED_ALGORITHMS.include?(signing_algorithm)
+              raise UnsupportedAlgorithmError,
+                "signing_algorithm must be one of #{SUPPORTED_ALGORITHMS.inspect} (got #{signing_algorithm.inspect})."
+            end
+
+            key = parse_key(private_key)
+            validate_key!(key, signing_algorithm)
+
+            now = Time.now.to_i
+            header = { alg: signing_algorithm, typ: "JWT" }
+            claims = {
+              iss: client_id,
+              sub: client_id,
+              aud: audience,
+              exp: now + lifetime,
+              iat: now,
+              jti: SecureRandom.uuid,
+            }
+
+            signing_input = "#{base64url(JSON.generate(header))}.#{base64url(JSON.generate(claims))}"
+            "#{signing_input}.#{base64url(sign(key, signing_algorithm, signing_input))}"
+          end
+
+          private
+
+          def parse_key(private_key)
+            return private_key if private_key.is_a?(OpenSSL::PKey::PKey)
+
+            OpenSSL::PKey.read(private_key.to_s)
+          rescue OpenSSL::PKey::PKeyError => e
+            raise InvalidKeyError, "private_key could not be parsed as a PEM-encoded key: #{e.message}."
+          end
+
+          def validate_key!(key, signing_algorithm)
+            case signing_algorithm
+            when "ES256"
+              unless key.is_a?(OpenSSL::PKey::EC) && key.group.curve_name == "prime256v1"
+                raise InvalidKeyError, "ES256 requires an EC private key on the prime256v1 (P-256) curve."
+              end
+            when "RS256"
+              unless key.is_a?(OpenSSL::PKey::RSA)
+                raise InvalidKeyError, "RS256 requires an RSA private key."
+              end
+            end
+
+            return if key.private?
+
+            raise InvalidKeyError, "private_key must contain the private component to sign assertions."
+          end
+
+          def sign(key, signing_algorithm, signing_input)
+            der = key.sign(OpenSSL::Digest.new("SHA256"), signing_input)
+            return der unless signing_algorithm == "ES256"
+
+            ecdsa_der_to_raw(der)
+          end
+
+          # `OpenSSL::PKey::EC#sign` returns an ASN.1 DER `SEQUENCE { r, s }`,
+          # while JWS ES256 (RFC 7518 Section 3.4) requires the raw 64-byte
+          # `r || s` concatenation with each integer left-padded to 32 bytes.
+          def ecdsa_der_to_raw(der)
+            OpenSSL::ASN1.decode(der).value.map do |integer|
+              integer.value.to_s(16).rjust(ES256_COMPONENT_BYTES * 2, "0")
+            end.join.then { |hex| [hex].pack("H*") }
+          end
+
+          def base64url(data)
+            Base64.urlsafe_encode64(data, padding: false)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -21,15 +21,23 @@ module MCP
       # - `redirect_handler` - Callable invoked with the fully-built authorization
       #   URL (a `URI`). Implementations typically open the user's browser.
       # - `callback_handler` - Callable invoked after `redirect_handler`. Returns
-      #   `[code, state]` where `code` is the authorization code and `state` is
-      #   the `state` parameter received on the redirect URI.
+      #   `[code, state]` or `[code, state, iss]`, where `code` is the authorization code,
+      #   `state` is the `state` parameter received on the redirect URI, and `iss` is
+      #   the RFC 9207 `iss` parameter (or nil when the authorization response carried none).
+      #   Returning the 3-element form opts into SEP-2468 issuer validation: a present `iss`
+      #   must match the authorization server's issuer, and a nil `iss` is
+      #   rejected when the AS advertises `authorization_response_iss_parameter_supported`.
+      #   The 2-element form skips the check for backward compatibility.
       #
       # Optional keyword arguments:
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
-      #   an `InMemoryStorage`.
+      #   an `InMemoryStorage`. Persisted `client_information` is stamped with
+      #   an `"issuer"` member binding it to the authorization server that
+      #   issued it (SEP-2352); when the authorization server changes, the SDK discards
+      #   the stale registration and tokens and re-registers.
       # - `client_id_metadata_document_url` - URL where the client publishes its Client ID Metadata Document
       #   (`draft-ietf-oauth-client-id-metadata-document-00` and the MCP authorization specification).
       #   When the authorization server advertises `client_id_metadata_document_supported: true`,

data/lib/mcp/client/oauth.rb

@@ -5,14 +5,18 @@ require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"
 require_relative "oauth/pkce"
 require_relative "oauth/storage_backed_provider"
+require_relative "oauth/jwt_client_assertion"
 require_relative "oauth/provider"
 require_relative "oauth/client_credentials_provider"
+require_relative "oauth/id_jag_token_exchange"
+require_relative "oauth/cross_app_access_provider"
 
 module MCP
   class Client
     # OAuth client support for the MCP Authorization spec (PRM discovery,
     # Authorization Server metadata discovery, Dynamic Client Registration,
-    # OAuth 2.1 Authorization Code + PKCE, and the client_credentials grant).
+    # OAuth 2.1 Authorization Code + PKCE, the client_credentials grant,
+    # and the SEP-990 Enterprise Managed Authorization jwt-bearer grant).
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
     module OAuth
     end

data/lib/mcp/client/paginated_result.rb

@@ -4,10 +4,12 @@ module MCP
   class Client
     # Result objects returned by `list_tools`, `list_prompts`, `list_resources`, and `list_resource_templates`.
     # Each carries the page items, an optional opaque `next_cursor` string for continuing pagination,
-    # and an optional `meta` hash mirroring the MCP `_meta` response field.
-    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, keyword_init: true)
-    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, keyword_init: true)
-    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, keyword_init: true)
-    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, keyword_init: true)
+    # an optional `meta` hash mirroring the MCP `_meta` response field, and the optional SEP-2549
+    # cache hints `ttl_ms` (freshness lifetime in milliseconds; 0 means do not cache) and
+    # `cache_scope` (`"public"` or `"private"`) mirroring the `ttlMs`/`cacheScope` response fields.
+    ListToolsResult = Struct.new(:tools, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListPromptsResult = Struct.new(:prompts, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListResourcesResult = Struct.new(:resources, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
+    ListResourceTemplatesResult = Struct.new(:resource_templates, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true)
   end
 end