mcp 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f6233cbd083a14b47183b21558ee995c06953ef5bb8d9ea568eca8e69103de
-  data.tar.gz: 11697a1b6e71297211fac5ecf411ac381a064e66274ac9c9a9640087284859ad
+  metadata.gz: 3585a92ae036b5018c7edf6b4c77a4a5c07903084314459a58180df16d3f0e28
+  data.tar.gz: d543ab701b3589e5728dba998e9b7d66b52baabfa4e9cf272834024bc57340a0
 SHA512:
-  metadata.gz: ec9899cc307eb88706aded076b0e7be9bb2bdbf2fbf52c3d8f8f7a7ebe05dbb1da802ebfc8ea9bc1d5ecc18c361a2249488815c60175650203815a084aad9833
-  data.tar.gz: c43d95b541108f64ac594567e44f3de9e103f4f52c2c122ef0f0d90dcaa52b391b419c536cf4653c784299324a71c23c9bb7da9a7c4f9f69db87c2ab1d730871
+  metadata.gz: 2d8cdd94c440d86ed5c317cc4bd94b21279ea613be75956bc49de0ddb008a0b574f3ee15751053be78c249d420709a168f0810674dbeeea34d9cd359dd9ac2f0
+  data.tar.gz: 9f131703b9db0f7fdfbc0a57ffe7b4132c522720bf841aaa4d70f20487644fe6ef428f89f4f39d4c1044312045553356fe87c3684f1deadc95dc81b45e441d42

data/README.md

@@ -6,7 +6,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 
 ## Features
 
-- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
+- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host, with OAuth 2.1 resource-server protection
 - Build [MCP clients](https://ruby.sdk.modelcontextprotocol.io/client/) that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
 - Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
 - Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination

data/lib/mcp/client/http.rb

@@ -202,9 +202,10 @@ module MCP
 
             if parsed.key?("result") || parsed.key?("error")
               @response ||= parsed
-            elsif parsed["method"] && parsed.key?("id")
-              # A server-to-client request (e.g. `elicitation/create`) delivered
-              # on the stream while the original request is still pending.
+            elsif parsed["method"] && parsed.key?("id") && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+              # A server-to-client request (e.g. `elicitation/create`) delivered on the stream while
+              # the original request is still pending. One that is not JSON-RPC 2.0 is dropped unanswered,
+              # as the TypeScript client drops it at schema validation.
               @on_request&.call(parsed)
             end
           end
@@ -399,6 +400,7 @@ module MCP
           )
         end
 
+        request_id = request[:id] || request["id"]
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
         oauth_retried = false
@@ -417,14 +419,20 @@ module MCP
           yield if block_given?
 
           response = begin
-            client.post("", request, session_headers.merge(request_metadata_headers(method, params))) do |req|
-              req.options.on_data = stream.on_data
+            redacting_authorization_header do
+              client.post("", request, session_headers.merge(request_metadata_headers(method, params))) do |req|
+                req.options.on_data = stream.on_data
+              end
             end
           rescue StreamAbort
             nil
           end
 
-          body = resolve_response_body(stream, response, method, params)
+          body = resolve_response_body(stream, response, request_id, method, params)
+
+          # Every way a response arrives (JSON body, SSE event, resumed stream) ends here. Checked before
+          # anything is learned from the body, and only for a request: a notification awaits no response.
+          reject_invalid_response!(body, method, params) if request_id
 
           capture_session_info(method, response, body) if response
           capture_mcp_param_declarations(method, params, body)
@@ -522,7 +530,7 @@ module MCP
       def send_notification(notification:)
         method = notification[:method] || notification["method"]
 
-        client.post("", notification, session_headers)
+        redacting_authorization_header { client.post("", notification, session_headers) }
         nil
       rescue Faraday::Error => e
         raise RequestHandlerError.new(
@@ -550,7 +558,7 @@ module MCP
         end
 
         begin
-          client.delete("", nil, session_headers)
+          redacting_authorization_header { client.delete("", nil, session_headers) }
         rescue Faraday::ClientError => e
           raise unless [404, 405].include?(e.response&.dig(:status))
         ensure
@@ -1045,6 +1053,51 @@ module MCP
         [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0.001].max
       end
 
+      # Runs a request on the transport's connection and, when Faraday raises, replaces the value of the `Authorization` header
+      # in the request headers the exception retains before it leaves the transport.
+      # Faraday's `raise_error` middleware keeps a reference to `env.request_headers` in `Faraday::Error#response`
+      # under `:request`, so the exception that becomes `RequestHandlerError#original_error` (and its `cause`) would otherwise print
+      # the bearer token through `inspect`, which is what error reporters and log lines do with it. The request is complete by
+      # the time the exception surfaces, and every request builds its own headers from the connection's defaults,
+      # so the rewrite reaches neither those defaults nor a later request.
+      def redacting_authorization_header
+        yield
+      rescue Faraday::Error => e
+        redact_authorization_header!(e)
+        raise
+      end
+
+      # `raise_error` retains the request as a Hash under `:request`; a JSON middleware the customizer added raises
+      # `Faraday::ParsingError` with the `Faraday::Response` itself, whose `env` holds the request headers.
+      def redact_authorization_header!(error)
+        response = error.response
+
+        if response.is_a?(Hash)
+          request = response[:request]
+          redact_authorization_header_in!(request, :headers) if request.is_a?(Hash)
+        elsif response.respond_to?(:env) && response.env.respond_to?(:request_headers)
+          redact_authorization_header_in!(response.env, :request_headers)
+        end
+      end
+
+      # The headers are a `Faraday::Utils::Headers`, which spells the name `Authorization` whatever the caller wrote,
+      # unless a customizer middleware replaced them with a plain Hash or froze them: the name is matched regardless
+      # of case so such a Hash is covered too, and a frozen object is swapped for a copy, so the redaction never
+      # raises in place of the error it is redacting.
+      def redact_authorization_header_in!(holder, key)
+        headers = holder[key]
+        return unless headers.is_a?(Hash)
+
+        names = headers.each_key.select { |name| name.to_s.casecmp?("authorization") }
+        return if names.empty?
+
+        headers = holder[key] = headers.dup if headers.frozen?
+
+        names.each do |name|
+          headers[name] = "[redacted]"
+        end
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -1054,8 +1107,11 @@ module MCP
       end
 
       # Determines the logical JSON-RPC body of the exchange after the POST stream finished
-      # (or was aborted because the response already arrived).
-      def resolve_response_body(stream, response, method, params)
+      # (or was aborted because the response already arrived). A notification (no `request_id`) awaits
+      # no response, so any success status acknowledges it, as it does for the TypeScript and Python clients,
+      # which check the content type of a response only for a request; the spec has the server answer
+      # a notification with 202, but a server answering with another 2xx is accepted as well.
+      def resolve_response_body(stream, response, request_id, method, params)
         return stream.response if stream.response
 
         # 202 Accepted is the server's ACK for a JSON-RPC notification or response; no body is expected.
@@ -1073,6 +1129,9 @@ module MCP
             return stream.response if stream.response
           end
 
+          # A stream that ends without a response has acknowledged a notification; there is nothing to resume for.
+          return if request_id.nil? && response.success?
+
           # SEP-1699: a graceful close after a priming event (an event with an id) but before
           # the response means "reconnect via GET to resume".
           return await_response_after_disconnect(stream, method, params) if stream.primed?
@@ -1089,6 +1148,8 @@ module MCP
           # added by the Faraday customizer may have parsed it already.
           response.body.is_a?(String) ? parse_json_buffer(response.body, method, params) : response.body
         else
+          return if request_id.nil? && response.success?
+
           raise RequestHandlerError.new(
             "Unsupported Content-Type: #{content_type.inspect}. Expected application/json or text/event-stream.",
             { method: method, params: params },
@@ -1157,7 +1218,7 @@ module MCP
       end
 
       def send_client_response(response)
-        client.post("", response, session_headers)
+        redacting_authorization_header { client.post("", response, session_headers) }
       end
 
       def parse_json_buffer(buffer, method, params)
@@ -1172,6 +1233,20 @@ module MCP
         )
       end
 
+      # A response is a JSON object whose `jsonrpc` is exactly "2.0". No body at all (202, or an empty 200)
+      # is not a message and is left to the caller as before; a JSON `null` body parses to the same `nil`.
+      # The received value is left out of the message because it can be any JSON value.
+      def reject_invalid_response!(body, method, params)
+        return if body.nil?
+        return if body.is_a?(Hash) && JsonRpcHandler.valid_version?(body["jsonrpc"])
+
+        raise RequestHandlerError.new(
+          'Server response is not a valid JSON-RPC 2.0 message: "jsonrpc" must be "2.0"',
+          { method: method, params: params },
+          error_type: :parse_error,
+        )
+      end
+
       # SEP-1699 resumability: the server closed the SSE stream after a priming event
       # without delivering the response. Treat the graceful close like a network failure:
       # wait the `retry:` interval the server asked for (default 1000ms), then reconnect with
@@ -1206,12 +1281,14 @@ module MCP
           read_timeout = remaining_reconnection_budget(deadline)
 
           reconnect_response = begin
-            client.get("") do |req|
-              req.headers.update(session_headers)
-              req.headers["Accept"] = SSE_ACCEPT_HEADER
-              req.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
-              req.options.read_timeout = read_timeout
-              req.options.on_data = stream.on_data
+            redacting_authorization_header do
+              client.get("") do |req|
+                req.headers.update(session_headers)
+                req.headers["Accept"] = SSE_ACCEPT_HEADER
+                req.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
+                req.options.read_timeout = read_timeout
+                req.options.on_data = stream.on_data
+              end
             end
           rescue StreamAbort
             # The awaited response arrived on the reconnected stream.

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

@@ -19,6 +19,9 @@ module MCP
         METADATA_DIAGNOSTIC_MAX_LENGTH = 128
         METADATA_URL_MAX_LENGTH = 2048
 
+        # RFC 6749 scope-token: visible ASCII except space, double quote, and backslash.
+        SCOPE_TOKEN_FORMAT = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/.freeze
+
         # Token request parameters the flow sets itself. Its values win over a provider's `token_request_params`,
         # so a provider naming one of these is refused rather than left believing its value was sent.
         RESERVED_TOKEN_REQUEST_PARAMS = [
@@ -264,12 +267,14 @@ module MCP
 
           ensure_pkce_supported!(as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm)
+          effective_scope = resolve_scope(scope: scope, prm: prm, select_prm_scope: true)
           effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
+          endpoint_uri, endpoint_params = authorization_endpoint_parameters(as_metadata: as_metadata)
+          request_scope = authorization_request_scope(scope: effective_scope, endpoint_params: endpoint_params)
 
           # Asked before registering, not after: a refusal must not leave this client registered at an authorization server
-          # the embedding application has just rejected.
-          authorize_request!(as_metadata: as_metadata, scope: effective_scope, server_url: server_url, resource: resource)
+          # the embedding application has just rejected. Use the scopes that will actually reach the browser URL.
+          authorize_request!(as_metadata: as_metadata, scope: request_scope, server_url: server_url, resource: resource)
 
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
@@ -277,7 +282,8 @@ module MCP
           state = SecureRandom.urlsafe_base64(32)
 
           authorization_url = build_authorization_url(
-            as_metadata: as_metadata,
+            endpoint_uri: endpoint_uri,
+            endpoint_params: endpoint_params,
             client_id: client_info_required_value(client_info, "client_id"),
             scope: effective_scope,
             state: state,
@@ -850,16 +856,16 @@ module MCP
         # Hands the embedding application the authorization server and the scopes that are about to be requested,
         # and abandons the flow when it refuses them.
         #
-        # Both values are chosen by the MCP server: it names its own authorization server in Protected
-        # Resource Metadata and states the scopes in `scopes_supported` or the `WWW-Authenticate` challenge.
+        # The MCP server names its authorization server in Protected Resource Metadata and states scopes
+        # in `scopes_supported` or the `WWW-Authenticate` challenge. Authorization-code policy also sees
+        # any prefilled endpoint scope that will survive URL assembly.
         # Neither the specification nor any MCP SDK binds that choice to the server's own identity,
         # and validating that a token was issued for the intended audience is a responsibility the specification
         # places on MCP servers rather than on clients.
         # A host that knows which providers its user deals with can apply that knowledge here.
         #
-        # The scopes are passed on unchanged whatever the host decides, because the specification requires
-        # a client to treat the challenged scopes as authoritative for the operation; the choice offered is
-        # to proceed or to stop, not to quietly ask for less. A provider without the hook proceeds as before.
+        # Challenged scopes are authoritative for the operation and bypass the PRM scope selector.
+        # The validator can accept or refuse them, not quietly request fewer scopes.
         #
         # Only asked when a new grant is being requested. A refresh is not a new grant, and the host already answered
         # this question for that authorization server, so `refresh!` enforces `ensure_token_issuer!` instead:
@@ -1302,17 +1308,18 @@ module MCP
           AuthorizationError.new(message, error: error, error_description: description)
         end
 
-        # Per MCP 2025-11-25 Authorization and the TS/Python SDKs, scope resolution
-        # prefers the `WWW-Authenticate` challenge first, then `scopes_supported`
-        # from the Protected Resource Metadata, and falls back to a provider-supplied
-        # scope only if both are absent. The provider-supplied scope must not pre-empt
-        # a server-advertised one.
-        def resolve_scope(scope:, prm:)
+        # MCP scope selection prefers the challenge, then PRM `scopes_supported`, then the provider's fallback.
+        # Authorization-code clients may narrow only the PRM default, before `offline_access` augmentation.
+        def resolve_scope(scope:, prm:, select_prm_scope: false)
           return scope if scope && !scope.empty?
 
           # `prm` is nil on the legacy path, where nothing advertises scopes.
           supported = prm && prm["scopes_supported"]
-          return supported.join(" ") if supported.is_a?(Array) && !supported.empty?
+          if supported.is_a?(Array) && !supported.empty?
+            return select_prm_scopes(supported) if select_prm_scope
+
+            return supported.join(" ")
+          end
 
           return @provider.scope if @provider.scope && !@provider.scope.empty?
 
@@ -1334,7 +1341,8 @@ module MCP
         #   the authorization request even though the AS will not honour it. Stripping here keeps the SDK's
         #   own request consistent with the AS's advertisement.
         #
-        # Returns `nil` when the result is empty so `build_authorization_url` omits the `scope` parameter entirely.
+        # Returns `nil` when empty so the URL builder adds no flow-owned scope parameter; a prefilled scope
+        # can still survive and is checked by the authorization-request validator.
         # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
         def normalize_offline_access_scope(scope, as_metadata:)
           scopes = scope.to_s.split
@@ -1354,6 +1362,28 @@ module MCP
           supported.is_a?(Array) && supported.include?("offline_access")
         end
 
+        # Selects a subset of the PRM default without changing challenges, provider fallback, or refresh policy.
+        def select_prm_scopes(scopes)
+          selector = @provider.scope_selector if @provider.respond_to?(:scope_selector)
+          return scopes.join(" ") unless selector
+
+          unless scopes.all? { |token| token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) }
+            raise AuthorizationError, "Protected Resource Metadata `scopes_supported` contains invalid OAuth scope tokens."
+          end
+
+          candidates = scopes.map { |token| token.dup.freeze }.freeze
+          candidate_index = candidates.to_h { |token| [token, true] }
+          selected = selector.call(candidates)
+          valid = selected.is_a?(Array) && selected.all? do |token|
+            token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) && candidate_index.key?(token)
+          end
+          unless valid
+            raise ArgumentError, "scope_selector must return an Array containing only scopes from PRM scopes_supported."
+          end
+
+          selected.empty? ? nil : selected.join(" ")
+        end
+
         def wants_refresh_token?
           metadata = @provider.client_metadata
           grant_types = metadata[:grant_types] || metadata["grant_types"]
@@ -1398,7 +1428,7 @@ module MCP
           @provider.client_id_metadata_document_url
         end
 
-        def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
+        def authorization_endpoint_parameters(as_metadata:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint
             raise AuthorizationError,
@@ -1412,6 +1442,23 @@ module MCP
               "Authorization server metadata `authorization_endpoint` is not a valid URI: #{e.message}."
           end
 
+          [uri, URI.decode_www_form(uri.query.to_s)]
+        end
+
+        # A flow scope replaces every endpoint scope; otherwise a single prefilled value survives.
+        # Decode once before policy approval and reuse those parameters when building the URL.
+        def authorization_request_scope(scope:, endpoint_params:)
+          return scope if scope
+
+          endpoint_scopes = endpoint_params.filter_map { |name, value| value if name == "scope" }
+          if endpoint_scopes.length > 1
+            raise AuthorizationError, "Authorization endpoint contains repeated `scope` parameters."
+          end
+
+          endpoint_scopes.first
+        end
+
+        def build_authorization_url(endpoint_uri:, endpoint_params:, client_id:, scope:, state:, code_challenge:, resource:)
           # A parameter the flow sets replaces any of the same name the endpoint URL already carries.
           # RFC 6749 Section 3.1 forbids sending a parameter twice, and which of two values a server would honor is
           # its own choice; on the legacy path the endpoint URL is served by the MCP server, whose query must not speak
@@ -1433,10 +1480,10 @@ module MCP
           own_params << ["resource", resource] if resource
           dropped_names = own_params.map(&:first) + ["request", "request_uri"]
 
-          params = URI.decode_www_form(uri.query.to_s).reject { |name, _value| dropped_names.include?(name) }
-          uri.query = URI.encode_www_form(params + own_params)
+          params = endpoint_params.reject { |name, _value| dropped_names.include?(name) }
+          endpoint_uri.query = URI.encode_www_form(params + own_params)
 
-          uri
+          endpoint_uri
         end
 
         def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)

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

@@ -37,6 +37,10 @@ module MCP
       #   `run!` saves it, when `callback_handler` is omitted. Defaults to `DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
+      # - `scope_selector` - Callable receiving a read-only Array of PRM `scopes_supported` tokens when
+      #   those defaults are selected without a challenged scope. Return an Array containing a subset;
+      #   `[]` requests none of the PRM defaults. Challenged scopes and provider fallback bypass it.
+      #   The existing `offline_access` policy runs afterward; endpoint query parameters are unchanged.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`. Persisted `client_information` is stamped with
@@ -108,6 +112,7 @@ module MCP
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
+          :scope_selector,
           :storage,
           :redirect_handler,
           :callback_handler,
@@ -120,6 +125,7 @@ module MCP
           redirect_handler:,
           callback_handler: nil,
           scope: nil,
+          scope_selector: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
           authorization_request_validator: nil,
@@ -147,6 +153,10 @@ module MCP
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          unless scope_selector.nil? || scope_selector.respond_to?(:call)
+            raise ArgumentError, "scope_selector must respond to call (got #{scope_selector.class})."
+          end
+
           http_client_customizer = validated_http_client_customizer(http_client_customizer)
 
           unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
@@ -170,6 +180,7 @@ module MCP
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
+          @scope_selector = scope_selector
           @storage = storage
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator

data/lib/mcp/client/stdio.rb

@@ -442,17 +442,22 @@ module MCP
           # other server-to-client requests over stdio stay unsupported as documented,
           # and notifications carry no id.
           if parsed.is_a?(Hash) && parsed.key?("method")
-            # A JSON-RPC id is a String or a Number; the reference SDKs reject other shapes at
-            # schema validation, so a ping carrying one is skipped rather than echoed back.
-            answer_ping(parsed) if parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"])
+            # A JSON-RPC id is a String or a Number, and `jsonrpc` is "2.0"; the reference SDKs reject
+            # other shapes at schema validation, so a ping carrying one is skipped rather than echoed back.
+            answer_ping(parsed) if answerable_ping?(parsed)
             next
           end
 
           # A JSON-RPC message is an object; skip a non-object frame (array or scalar)
           # the same way as a frame without an id.
           next unless parsed.is_a?(Hash) && parsed.key?("id")
+          next unless parsed["id"] == request_id
 
-          return parsed if parsed["id"] == request_id
+          # Nothing else will answer the awaited request, so a response that is not JSON-RPC 2.0 fails it
+          # instead of being skipped: without a `read_timeout`, skipping would wait forever.
+          raise_invalid_response!(method, params) unless JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+
+          return parsed
         end
       rescue JSON::ParserError => e
         raise RequestHandlerError.new(
@@ -475,6 +480,10 @@ module MCP
         # surface as an error of the unrelated request whose response the loop is reading.
       end
 
+      def answerable_ping?(parsed)
+        parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"]) && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+      end
+
       def json_rpc_id?(id)
         id.is_a?(String) || id.is_a?(Numeric)
       end
@@ -532,6 +541,16 @@ module MCP
           error_type: :internal_error,
         )
       end
+
+      # The line framing is intact, so the transport stays usable; the received value is left out of
+      # the message because it can be any JSON value.
+      def raise_invalid_response!(method, params)
+        raise RequestHandlerError.new(
+          'Server response is not a valid JSON-RPC 2.0 message: "jsonrpc" must be "2.0"',
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
     end
   end
 end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MCP
+  class Server
+    module OAuth
+      # The result of a successful token verification: the resource-server-side view of an access token.
+      # Instances are produced by a `TokenVerifier` and reach tool/prompt/resource handlers as `server_context.auth_info`.
+      #
+      # The field set is the union of what the official SDKs converged on (Python `AccessToken` and TypeScript `AuthInfo`):
+      #
+      # - `token` - the raw bearer token as presented by the client
+      # - `client_id` - the OAuth client the token was issued to
+      # - `scopes` - granted scopes as an array of strings
+      # - `expires_at` - expiry as an Integer unix timestamp, or nil when the token does not expire
+      # - `subject` - the end user (`sub` claim), when known
+      # - `issuer` - the authorization server that issued the token (`iss` claim)
+      # - `audience` - the raw `aud` value (String or Array), when known
+      # - `resource` - the canonical RFC 8707 resource identifier the verifier matched the token against,
+      #   useful for tenancy checks inside handlers
+      # - `claims` - the full claim/introspection-response Hash for anything not covered by the named fields
+      class AccessToken
+        attr_reader :token, :client_id, :scopes, :expires_at, :subject, :issuer, :audience, :resource, :claims
+
+        def initialize(token:, client_id: nil, scopes: [], expires_at: nil, subject: nil, issuer: nil, audience: nil, resource: nil, claims: {})
+          @token = token
+          @client_id = client_id
+          @scopes = scopes
+          @expires_at = expires_at
+          @subject = subject
+          @issuer = issuer
+          @audience = audience
+          @resource = resource
+          @claims = claims
+          @scope_matcher = nil
+        end
+
+        # Per RFC 7519 Section 4.1.4, a token must not be accepted on or after its expiry time.
+        # Tokens without an expiry never count as expired here; verifiers that require an expiry must enforce that themselves
+        # (`JWTVerifier` does, the TypeScript SDK rejects such tokens outright, and Python accepts them like this class —
+        # the divergence is deliberate: opaque-token verifiers may have no expiry to report even though the authorization server enforces one).
+        def expired?(now: Time.now.to_i)
+          return false if expires_at.nil?
+
+          expires_at <= now
+        end
+
+        # Whether the token grants `scope`: exact membership by default. When the authenticator attached its `scope_matcher:`
+        # (see `with_scope_matcher`), that callable decides instead, so a hierarchical scope scheme is honored the same way
+        # at the endpoint gate and inside handlers via `require_scopes!`.
+        def scope?(scope)
+          return scopes.include?(scope.to_s) if @scope_matcher.nil?
+
+          !!@scope_matcher.call(scope.to_s, scopes)
+        end
+
+        # A copy of this token whose `scope?` consults `matcher`, a `(required_scope, granted_scopes) -> Boolean` callable.
+        # The receiver is left untouched; a nil matcher returns the receiver itself.
+        def with_scope_matcher(matcher)
+          return self if matcher.nil?
+
+          dup.tap { |copy| copy.scope_matcher = matcher }
+        end
+
+        # Mirrors `to_h`: the default `inspect` would print `@token`, leaking the credential into exception reports and debug output.
+        def inspect
+          "#<#{self.class.name} #{to_h.inspect}>"
+        end
+
+        # Omits `token` so the result is safe to log without leaking the credential.
+        def to_h
+          {
+            client_id: client_id,
+            scopes: scopes,
+            expires_at: expires_at,
+            subject: subject,
+            issuer: issuer,
+            audience: audience,
+            resource: resource,
+            claims: claims,
+          }.compact
+        end
+
+        protected
+
+        attr_writer :scope_matcher
+      end
+    end
+  end
+end