mcp 1.6.1 → 1.8.0

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 = [
@@ -83,6 +86,27 @@ module MCP
         # and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
         class DestinationMismatchError < ArgumentError; end
 
+        # Raised by `MCP::Client::HTTP` when a provider without a `callback_handler` has sent the user to the authorization server:
+        # the request cannot be retried until the application finishes the authorization with `finish!` in the request that
+        # receives the redirect. `authorization_url` is the URL handed to `redirect_handler`; it is kept out of the message,
+        # which may reach logs, because it carries the `state` that `finish!` looks the pending authorization up by.
+        # Deliberately outside `AuthorizationError`, which `MCP::Client::HTTP` treats on a failed refresh as a reason to run
+        # the interactive flow: this is the interactive flow waiting on the user, not a failure.
+        class AuthorizationPendingError < StandardError
+          attr_reader :authorization_url
+
+          def initialize(message = nil, authorization_url: nil)
+            super(message)
+            @authorization_url = authorization_url
+          end
+        end
+
+        # A `state` the SDK generates is 43 characters; a callback carrying a much longer one is refused before storage is asked.
+        CALLBACK_STATE_MAX_LENGTH = 128
+
+        UNKNOWN_PENDING_AUTHORIZATION_MESSAGE =
+          "Authorization callback `state` matches no pending authorization; it is unknown, already used, or expired."
+
         # Faraday middleware registered on the connection `build_http_client` assembles before the customizer
         # is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
         # as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
@@ -189,13 +213,20 @@ module MCP
           end
         end
 
+        # The authorization URL the last `run!` handed to `redirect_handler` before returning `:redirect`, or `nil`.
+        attr_reader :authorization_url
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
+          @authorization_url = nil
         end
 
         # Runs the full discovery, registration, authorization, and token exchange flow.
         # On success, persists tokens via the provider and returns `:authorized`.
+        # A provider without a `callback_handler` stops after the redirect instead: the flow saves
+        # a pending authorization in the provider's storage, keyed by `state`, and returns `:redirect`, leaving the code
+        # exchange to `finish!` in the request that receives the redirect.
         def run!(server_url:, resource_metadata_url: nil, scope: nil)
           # The `resource_metadata` URL ships in `WWW-Authenticate` and is the very
           # first thing we contact in the OAuth flow, so it has to clear the same
@@ -236,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)
 
@@ -249,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,
@@ -257,6 +291,20 @@ module MCP
             resource: resource,
           )
 
+          if @provider.callback_handler.nil?
+            save_pending_authorization(
+              state: state,
+              code_verifier: pkce[:code_verifier],
+              server_url: server_url,
+              resource: resource,
+              client_id: client_info_required_value(client_info, "client_id"),
+              as_metadata: as_metadata,
+            )
+            @authorization_url = authorization_url
+            @provider.redirect_handler.call(authorization_url)
+            return :redirect
+          end
+
           @provider.redirect_handler.call(authorization_url)
           callback_result = Array(@provider.callback_handler.call)
           code, returned_state, returned_iss = callback_result
@@ -449,6 +497,87 @@ module MCP
           :refreshed
         end
 
+        # Finishes an authorization that `run!` left pending, in the request that receives the redirect to `redirect_uri`,
+        # which may run in another process. `callback_params` is that redirect's whole query as a Hash (`code`, `state`, and,
+        # when present, `iss`, `error`, and `error_description`); passing all of it, rather than picking values out, is
+        # the caller's part of the `iss` check: an `iss` the caller drops reads as absent, and the flow cannot tell the difference.
+        #
+        # The pending authorization is looked up by `state` before any request is made, and it binds the rest of the exchange:
+        # the code is redeemed at the token endpoint recorded when the authorization began, with the client registration,
+        # `resource`, and `redirect_uri` used then, and without discovery running again, so the code reaches the authorization
+        # server the user was sent to (SEP-2352). The RFC 9207 `iss` is validated against the recorded issuer before the pending
+        # authorization is consumed, so a callback from another authorization server, as in a mix-up, is refused without
+        # consuming the entry the legitimate callback needs, and before the callback's `error` is read, since in a mix-up
+        # those parameters are the other server's. The check establishes only that a present `iss` matches the recorded issuer,
+        # not who sent the callback, and a callback without `iss` passes it unless the metadata advertises
+        # `authorization_response_iss_parameter_supported`: whoever holds the `state`, passes that check, and reaches
+        # the consume first takes the entry, and the legitimate callback then finds nothing.
+        #
+        # Past that check the pending authorization is consumed with `delete_pending_authorization`, which returns the entry
+        # it removed; only a callback that gets the entry back redeems the code, so of callbacks racing on the same `state`
+        # (a retried redirect, say), at most one does.
+        #
+        # Binding the callback to the user who started the authorization stays with the application: scoping `storage`
+        # to that user means a callback delivered to another user's session finds no pending authorization.
+        #
+        # On success, persists tokens via the provider and returns `:authorized`.
+        def finish!(server_url:, callback_params:)
+          unless provider_authorization_flow == :authorization_code && @provider.callback_handler.nil?
+            raise ArgumentError,
+              "finish! completes an authorization started by a provider without a callback_handler; " \
+                "this provider finishes its authorizations in `run!`."
+          end
+
+          state = callback_param(callback_params, "state")
+          raise AuthorizationError, "Authorization callback carried no `state`." unless state
+
+          pending = @provider.pending_authorization(state) if state.bytesize <= CALLBACK_STATE_MAX_LENGTH
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(pending)
+
+          if pending_authorization_expired?(pending)
+            @provider.delete_pending_authorization(state)
+            raise AuthorizationError, "The pending authorization has expired; start a new authorization."
+          end
+
+          unless safe_canonicalize_url(server_url, label: "MCP server URL") == pending["server_url"]
+            raise AuthorizationError, "The pending authorization was started for a different MCP server."
+          end
+
+          as_metadata = pending["authorization_server_metadata"]
+          # Checked when the authorization began, and checked again because the metadata has since made a round trip
+          # through the application's storage.
+          ensure_secure_endpoints!(as_metadata, server_url: pending["server_url"])
+
+          validate_authorization_response_issuer!(
+            as_metadata: as_metadata,
+            iss: callback_param(callback_params, "iss"),
+            iss_provided: true,
+          )
+
+          # The read above and this delete are separate calls, so the storage's atomic delete is what decides
+          # which of two concurrent callbacks carrying this `state` proceeds.
+          consumed = @provider.delete_pending_authorization(state)
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(consumed)
+
+          error = callback_param(callback_params, "error")
+          raise authorization_response_error(error, callback_param(callback_params, "error_description")) if error
+
+          code = callback_param(callback_params, "code")
+          raise AuthorizationError, "Authorization callback carried no authorization code." unless code
+
+          tokens = exchange_authorization_code(
+            as_metadata: as_metadata,
+            client_info: pending_client_information(pending, as_metadata: as_metadata),
+            code: code,
+            code_verifier: pending["code_verifier"],
+            resource: pending["resource"],
+            redirect_uri: pending["redirect_uri"],
+          )
+
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
+          :authorized
+        end
+
         private
 
         def read_token(key)
@@ -727,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:
@@ -1096,17 +1225,101 @@ module MCP
           result.zero?
         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:)
+        def provider_pending_authorization_max_age
+          return Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE unless @provider.respond_to?(:pending_authorization_max_age)
+
+          @provider.pending_authorization_max_age
+        end
+
+        # Records what `finish!` needs to redeem the code exactly as this authorization began: the PKCE verifier, the MCP server,
+        # the `resource` and `redirect_uri` sent, the client identity used, and the authorization server metadata already validated.
+        # The client secret is not copied: `finish!` reads the registration from storage and requires the same `client_id`.
+        # Every value is JSON-compatible, so storage can serialize the entry as-is.
+        def save_pending_authorization(state:, code_verifier:, server_url:, resource:, client_id:, as_metadata:)
+          @provider.save_pending_authorization(
+            state,
+            {
+              "code_verifier" => code_verifier,
+              "server_url" => safe_canonicalize_url(server_url, label: "MCP server URL"),
+              "resource" => resource,
+              "redirect_uri" => @provider.redirect_uri,
+              "client_id" => client_id,
+              "authorization_server_metadata" => as_metadata,
+              "created_at" => Time.now.to_i,
+            },
+          )
+        end
+
+        def valid_pending_authorization?(pending)
+          return false unless pending.is_a?(Hash)
+          return false unless ["code_verifier", "server_url", "redirect_uri", "client_id"].all? { |key| non_empty_string?(pending[key]) }
+          return false unless pending["resource"].nil? || non_empty_string?(pending["resource"])
+
+          pending["authorization_server_metadata"].is_a?(Hash) && pending["created_at"].is_a?(Integer)
+        end
+
+        def pending_authorization_expired?(pending)
+          Time.now.to_i - pending["created_at"] > provider_pending_authorization_max_age
+        end
+
+        # The registration the authorization began with. A stored registration is used only while it still carries
+        # that `client_id` and is bound to the recorded authorization server; a Client ID Metadata Document URL,
+        # which is never stored, is used again while the recorded metadata advertises support for it.
+        def pending_client_information(pending, as_metadata:)
+          client_id = pending["client_id"]
+
+          stored = @provider.client_information
+          if stored.is_a?(Hash) &&
+              client_info_required_value(stored, "client_id") == client_id &&
+              client_info_required_value(stored, "issuer") == as_metadata["issuer"]
+            return stored
+          end
+
+          if client_id == provider_client_id_metadata_document_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => client_id }
+          end
+
+          raise AuthorizationError, "The client registration changed after the authorization began; start a new authorization."
+        end
+
+        # Reads one parameter of an authorization response. Only a non-empty String counts: a repeated parameter that
+        # a framework delivers as an Array, or an empty value, is treated as absent.
+        def callback_param(params, key)
+          return unless params.is_a?(Hash)
+
+          value = params[key] || params[key.to_sym]
+          non_empty_string?(value) ? value : nil
+        end
+
+        def non_empty_string?(value)
+          value.is_a?(String) && !value.empty?
+        end
+
+        # An RFC 6749 Section 4.1.2.1 error response, reported with the bounds a token endpoint error gets.
+        # Reached only after the `iss` check, so any `iss` beside the values matched the recorded issuer; that does not
+        # prove who sent them, and they are text the sender chose, so they are cut to a bounded length and confined to
+        # the printable ASCII the RFC permits.
+        def authorization_response_error(error, description)
+          error = bounded_diagnostic(error, limit: TOKEN_ENDPOINT_ERROR_MAX_LENGTH)
+          description = bounded_diagnostic(description, limit: TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH)
+          message = "The authorization server returned an error to the authorization callback."
+          message += " #{[error, description].compact.join(": ")}" if error || description
+
+          AuthorizationError.new(message, error: error, error_description: description)
+        end
+
+        # 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?
 
@@ -1128,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
@@ -1148,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"]
@@ -1192,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,
@@ -1206,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
@@ -1227,17 +1480,17 @@ 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:)
+        def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)
           form = {
             "grant_type" => "authorization_code",
             "code" => code,
-            "redirect_uri" => @provider.redirect_uri,
+            "redirect_uri" => redirect_uri,
             "code_verifier" => code_verifier,
           }
           form["resource"] = resource if resource

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

@@ -16,6 +16,17 @@ module MCP
       #   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.
       #
+      # A provider without a `callback_handler` also keeps each pending authorization here, keyed by its `state`,
+      # between the request that sends the user to the authorization server and the request that receives
+      # the redirect (`save_pending_authorization(state, pending)`, `pending_authorization(state)`,
+      # `delete_pending_authorization(state)`). A pending authorization holds the PKCE verifier, so custom storages
+      # should treat it as a secret and persist it as-is. `Flow#finish!` touches only the entry its callback's `state`
+      # names, so an authorization the user never finished stays until the storage drops it: this class drops entries
+      # older than `pending_authorization_max_age` the next time one is saved, and a custom storage should expire them,
+      # with a TTL of that age. `delete_pending_authorization` must remove the entry and return it in one atomic step
+      # (`Hash#delete` under a mutex here; `GETDEL` in Redis, `DELETE ... RETURNING` in SQL), returning `nil` when
+      # there was none: the flow redeems the code only when it gets the entry back.
+      #
       # This class keeps everything in process memory, so the credentials live
       # only for the lifetime of the Ruby process. Applications that need
       # persistence across restarts should supply a custom object responding to
@@ -24,12 +35,25 @@ module MCP
       # `Provider.new(storage: ...)`. The shape mirrors Python SDK's
       # `TokenStorage` Protocol; TypeScript's `OAuthClientProvider` rolls
       # the same responsibilities into a single object.
+      # A web application may receive the redirect in another process, so pending authorizations
+      # need shared storage.
       class InMemoryStorage
         attr_accessor :tokens, :client_information
 
-        def initialize
+        # @param pending_authorization_max_age [Integer] seconds after which a pending authorization that was
+        #   never finished is dropped from this storage, at its next save. `Provider.new` passes its own
+        #   `pending_authorization_max_age` when it builds the default storage, so the two ages agree; a storage built
+        #   by hand defaults to `Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
+        def initialize(pending_authorization_max_age: Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE)
+          unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
+            raise ArgumentError, "pending_authorization_max_age must be a positive Integer number of seconds (got #{pending_authorization_max_age.inspect})."
+          end
+
           @tokens = nil
           @client_information = nil
+          @pending_authorizations = {}
+          @pending_authorization_max_age = pending_authorization_max_age
+          @pending_authorizations_mutex = Mutex.new
         end
 
         def save_tokens(tokens)
@@ -39,6 +63,55 @@ module MCP
         def save_client_information(info)
           @client_information = info
         end
+
+        # Drops every pending authorization older than `pending_authorization_max_age` before saving the new one.
+        # The flow refuses such an entry when it is looked up, but only a callback carrying its `state` looks it up,
+        # and an authorization the user abandoned never gets one; every `401` a provider without a `callback_handler` meets
+        # starts another, so without this the entries, each holding the verifier and the authorization server metadata,
+        # would accumulate for the life of the process.
+        def save_pending_authorization(state, pending)
+          @pending_authorizations_mutex.synchronize do
+            drop_expired_pending_authorizations
+            @pending_authorizations[state] = pending
+          end
+        end
+
+        def pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations[state] }
+        end
+
+        # The mutex is what makes the removal and the return one step on every Ruby implementation: `Hash#delete`
+        # alone is atomic only where a global interpreter lock serializes it, and `Flow#finish!` relies on exactly
+        # one of two callbacks racing on the same `state` getting the entry back.
+        def delete_pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations.delete(state) }
+        end
+
+        # Every hash this storage holds may carry a secret (an access token, a client secret, a PKCE verifier),
+        # and `inspect` is what error reporters and consoles print an object with, so it shows only whether each is present.
+        def inspect
+          pending_count = @pending_authorizations_mutex.synchronize { @pending_authorizations.size }
+
+          "#<#{self.class.name} tokens=#{present_or_nil(@tokens)} client_information=#{present_or_nil(@client_information)} pending_authorizations=#{pending_count}>"
+        end
+
+        private
+
+        # An entry's age is read from the Integer `created_at` the flow records when it saves the entry; an entry without one,
+        # which the flow never writes, is left alone.
+        def drop_expired_pending_authorizations
+          now = Time.now.to_i
+
+          @pending_authorizations.delete_if do |_state, pending|
+            created_at = pending.is_a?(Hash) ? pending["created_at"] : nil
+
+            created_at.is_a?(Integer) && now - created_at > @pending_authorization_max_age
+          end
+        end
+
+        def present_or_nil(value)
+          value.nil? ? "nil" : "[present]"
+        end
       end
     end
   end