x-core 1.0.0

data/lib/x/core/oauth2_refresh.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "simple_oauth"
+require_relative "errors/authorization_error"
+require_relative "errors/unauthorized"
+require_relative "oauth2_tokens"
+require_relative "origin"
+require_relative "refresh_reporter"
+require_relative "setting_validator"
+require_relative "token_endpoint"
+
+module X
+  module Core
+    # How an OAuth2Authenticator refreshes its tokens, before a request and after a rejection, included into it
+    #
+    # Processes that share the tokens of a user read the store they share with load_tokens before a refresh, and take
+    # the tokens there in place of their own when those hold another refresh token, which another process issued
+    # by a refresh of its own. The tokens taken are copied, and never recorded as the latest a refresh issued, so the
+    # RefreshReporter passes them to no save_tokens: they came from the store.
+    #
+    # Internal to x-core: the methods are private, and a client calls retrying_rejected_token with __send__.
+    #
+    # @api private
+    module OAuth2Refresh
+      # The message raised when the token endpoint describes no reason for the failure
+      DEFAULT_ERROR_MESSAGE = "Token refresh failed"
+      private_constant :DEFAULT_ERROR_MESSAGE
+      # Seconds after a refresh in which a rejection of the access token it issued refreshes nothing
+      FRESH_TOKEN_SECONDS = 60
+      private_constant :FRESH_TOKEN_SECONDS
+      # The message of the error raised for load_tokens that returns what is not tokens
+      NOT_TOKENS = "load_tokens must return an X::OAuth2Tokens, or nil for none in the store, not a %s. Build the " \
+        "tokens from what the store holds with X::OAuth2Tokens.new"
+      private_constant :NOT_TOKENS
+      # The error codes of a refresh X refuses for a refresh token it no longer accepts, as one another process spent
+      REFUSED_REFRESH_TOKEN = %w[invalid_request invalid_grant].freeze
+      private_constant :REFUSED_REFRESH_TOKEN
+
+      private
+
+      # Initialize the lock, the reporter, and the loader of the refreshes
+      # @api private
+      # @param load_tokens [#call, nil] the callable that returns the OAuth2Tokens in the store, or nil for none
+      # @return [void]
+      # @raise [ArgumentError] if load_tokens is neither nil nor responds to call
+      def initialize_refresh(load_tokens)
+        @load_tokens = SettingValidator.callable!(:load_tokens, load_tokens)
+        @mutex = Mutex.new
+        @reporter = RefreshReporter.new
+        @spent_refresh_tokens = Set.new
+      end
+
+      # Refresh the access token if it has expired, over a connection
+      #
+      # An authenticator that holds no refresh token refreshes nothing, and sends the token it holds.
+      #
+      # @api private
+      # @param connection [Core::Connection] the connection to send the refresh over
+      # @param client [Client, nil] the client whose request refreshes, whose headers it is sent with, or nil for none
+      # @return [void]
+      # @raise [AuthorizationError] if X refuses to refresh the token
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      # @raise [TokenReportFailed] if save_tokens raises for the tokens of the refresh
+      def refresh_expired_token(connection, client = nil)
+        tokens = @mutex.synchronize { renew(connection, client) if refresh_token && token_expired? }
+        report_refresh(tokens, client) if tokens
+      end
+
+      # Refresh a rejected access token, unless it was already replaced or just issued
+      #
+      # Requests that were sent with the same token, and rejected together, refresh it once between them. A token
+      # issued by a refresh less than FRESH_TOKEN_SECONDS ago has not expired, so the API rejects it for another
+      # reason, which a refresh would not change: it is not refreshed, and the rejection is raised, rather than spend
+      # a refresh token on each request an endpoint that always rejects the token answers. An authenticator that holds no
+      # refresh token refreshes nothing, so the rejection is raised.
+      #
+      # @api private
+      # @param rejected_token [String] the access token the API rejected
+      # @param connection [Core::Connection] the connection to send the refresh over
+      # @param client [Client, nil] the client whose request the API rejected, whose headers the refresh is sent with,
+      #   or nil for none
+      # @return [Boolean] true if the access token is no longer the one rejected
+      # @raise [AuthorizationError] if X refuses to refresh the token
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      # @raise [TokenReportFailed] if save_tokens raises for the tokens of the refresh
+      def refresh_rejected_token!(rejected_token, connection, client = nil)
+        tokens, replaced = @mutex.synchronize do
+          [(renew(connection, client) if refresh_token && access_token.eql?(rejected_token) && !fresh?), !access_token.eql?(rejected_token)]
+        end
+        report_refresh(tokens, client) if tokens
+        replaced
+      end
+
+      # Run a request, again if the API rejects a token that a refresh replaces
+      #
+      # X rejects an expired access token with 401 Unauthorized, which an authenticator that does not know when
+      # its token expires learns only from the rejection. A 401 from another origin than the one the token is sent to
+      # answers a request that carried no token, whether it named that origin or was redirected there, so it refreshes
+      # nothing: X accepts a refresh token once, and a refresh would replace the tokens for a rejection of no token.
+      #
+      # A token that has expired is refreshed before the request, and one the API rejects after it, over the
+      # connection given, which is the one of the client that sends the request, with the headers of that client: the
+      # copies of a client share its authenticator, and a copy given another proxy, other timeouts, other debug output,
+      # or other headers refreshes the tokens it shares with them, as it sends its requests with them.
+      #
+      # Internal to x-core: Client runs each request it sends with an OAuth 2.0 authenticator through it, and calls it
+      # with __send__, since it is private.
+      #
+      # @api private
+      # @param origin [URI::Generic] a URI of the origin the token is sent to, such as the base URL of a client
+      # @param connection [Core::Connection] the connection to send a refresh over
+      # @param client [Client, nil] the client that sends the request, which TokenReportFailed holds, or nil for none
+      # @yield runs the request
+      # @return [Object] what the block returns
+      # @raise [Unauthorized] if the request is rejected again, or by another origin, or a refresh does not replace
+      #   the access token
+      # @raise [TokenReportFailed] if save_tokens raises for the tokens of a refresh, with the tokens and client
+      def retrying_rejected_token(origin, connection, client = nil)
+        refresh_expired_token(connection, client)
+        token = access_token
+        begin
+          yield
+        rescue Unauthorized => e
+          raise unless Origin.answered?(e, origin) && refresh_rejected_token!(token, connection, client)
+
+          yield
+        end
+      end
+
+      # Take the tokens in the store, or else refresh, holding the lock
+      #
+      # Tokens taken from the store whose access token has not expired are sent as they are, and the others refreshed
+      # with the refresh token there.
+      #
+      # @api private
+      # @param connection [Core::Connection] the connection to send the refresh over
+      # @param client [Client, nil] the client whose request refreshes, or nil for none
+      # @return [OAuth2Tokens, nil] the tokens the refresh issued, or those it took from the store in place of a
+      #   refusal, or nil for tokens taken from the store that need no refresh
+      # @raise [AuthorizationError] if X refuses to refresh the token
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      def renew(connection, client)
+        refresh(connection, client) unless adopt_stored_tokens && !token_expired?
+      end
+
+      # Refresh the access token, holding the lock
+      #
+      # It is called for an authenticator that holds a refresh token alone, which a refresh never takes away. A
+      # refresh X refuses for a refresh token it no longer accepts reads the store again, and takes the tokens there,
+      # if they hold another refresh token, in place of raising: another process spent the refresh token first.
+      #
+      # @api private
+      # @param connection [Core::Connection] the connection to send the refresh over
+      # @param client [Client, nil] the client whose request refreshes, or nil for none
+      # @return [OAuth2Tokens] the tokens the refresh issued, once the authenticator holds them, or those it took from
+      #   the store in place of a refusal
+      # @raise [AuthorizationError] if X refuses to refresh the token, and the store holds no other
+      # @raise [HTTPError, InvalidResponse] if the token endpoint limits the rate of the request or fails to answer,
+      #   as a server error, a redirect, or the page of a proxy says
+      def refresh(connection, client)
+        held = refresh_token #: String
+        request = oauth2_client(token_url(client)).refresh_token_request(refresh_token: held)
+        update_tokens(TokenEndpoint.fetch(request, connection:, refusal: DEFAULT_ERROR_MESSAGE, headers: token_headers(client)))
+        @spent_refresh_tokens << held
+        issued = refresh_token #: String
+        @reporter.issued(OAuth2Tokens.new(access_token:, refresh_token: issued, expires_at:, scopes:))
+      rescue AuthorizationError => e
+        adopt_in_place_of(e) or raise
+      end
+
+      # The headers a refresh is sent with
+      #
+      # A refresh a client's request makes is sent to the token endpoint at the origin of that client's base URL,
+      # with its headers, over its connection, and one made for no client, as refresh! and a request signed with the
+      # authenticator alone make, to the endpoint of the client that took the authenticator first, with its headers,
+      # over its connection.
+      #
+      # @api private
+      # @param client [Client, nil] the client whose request refreshes, or nil for none
+      # @return [Hash{String => String}] the headers
+      def token_headers(client) = client ? client.headers : @token_headers
+
+      # Take the stored tokens in place of a refused refresh
+      # @api private
+      # @param error [AuthorizationError] the refusal
+      # @return [OAuth2Tokens, nil] a copy of the tokens taken, or nil if X refused anything but the refresh token, or
+      #   the store holds no other
+      def adopt_in_place_of(error) = (adopt_stored_tokens if REFUSED_REFRESH_TOKEN.include?(error.error_code))
+
+      # Take the stored tokens, if they hold another refresh token
+      #
+      # Tokens that hold no refresh token, as an authorization without offline.access stores them, are not taken, since
+      # they would take away the refresh token of an authenticator that refreshes, which a refresh never does. Tokens
+      # that hold the refresh token the authenticator holds, or one any of its refreshes spent, are its own, as the
+      # store holds them until save_tokens has stored the tokens of a later refresh, which it is passed once the lock
+      # is released, so they are not taken: refreshes on several threads while save_tokens is slow leave the store
+      # holding tokens older than the last refresh spent, whose refresh token X no longer accepts. The age of the access token taken is unknown, so it is not fresh.
+      #
+      # @api private
+      # @return [OAuth2Tokens, nil] a copy of the tokens taken, or nil if the store holds none, or none of another's
+      def adopt_stored_tokens
+        stored = stored_tokens or return
+        stored_refresh_token = stored.refresh_token
+        return if stored_refresh_token.nil? || stored_refresh_token.eql?(refresh_token) || @spent_refresh_tokens.include?(stored_refresh_token)
+
+        @refreshed_at = nil
+        @access_token = stored.access_token
+        @refresh_token = stored.refresh_token
+        @expires_at = stored.expires_at
+        @scopes = stored.scopes
+        OAuth2Tokens.new(**stored.to_h)
+      end
+
+      # The tokens in the store the tokens of the user are shared through
+      #
+      # They are read with the load_tokens of the authenticator, or else with the load_tokens of a client that
+      # authenticates with it. The error names the class of what load_tokens returned, rather than inspect it, since a
+      # Hash of the tokens would show them.
+      #
+      # @api private
+      # @return [OAuth2Tokens, nil] the tokens, or nil for none in the store, or no load_tokens to read it with
+      # @raise [TypeError] if load_tokens returns neither OAuth2Tokens nor nil
+      def stored_tokens
+        load_tokens = @load_tokens || clients.keys.filter_map(&:load_tokens).first
+        stored = load_tokens&.call
+        raise TypeError, format(NOT_TOKENS, stored.class) unless stored.nil? || stored.is_a?(OAuth2Tokens)
+
+        stored
+      end
+
+      # Pass the tokens of a refresh to its callables, once the lock is released
+      #
+      # A callable can make a request of its own, such as looking up the user whose tokens it stores, which asks this
+      # authenticator for a header and so takes the lock again. The refreshes are reported in the order they were
+      # made, and one already replaced is not reported; see {Core::RefreshReporter}.
+      #
+      # @api private
+      # @param tokens [OAuth2Tokens] the tokens the refresh issued
+      # @param client [Client, nil] the client whose request refreshed, which TokenReportFailed holds, or nil for none
+      # @return [void]
+      # @raise [TokenReportFailed] if save_tokens raises for the tokens, with the tokens and client
+      def report_refresh(tokens, client) = @reporter.report(tokens, client)
+
+      # Update tokens from the response
+      # @api private
+      # @param token [SimpleOAuth::OAuth2::Token] the token the endpoint returned
+      # @return [void]
+      def update_tokens(token)
+        @refreshed_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @access_token = SettingValidator.frozen(token.access_token)
+        @refresh_token = SettingValidator.frozen(token.refresh_token) if token.refresh_token
+        @expires_at = token.expires_at
+        @scopes = TokenEndpoint.scopes_of(token) || scopes
+      end
+
+      # Check whether a refresh issued the access token within FRESH_TOKEN_SECONDS
+      #
+      # A token the authenticator was given, rather than refreshed, may be of any age, so it is not fresh.
+      #
+      # @api private
+      # @return [Boolean] true if a refresh issued the token less than FRESH_TOKEN_SECONDS ago
+      def fresh?
+        refreshed_at = @refreshed_at
+        !refreshed_at.nil? && Process.clock_gettime(Process::CLOCK_MONOTONIC) - refreshed_at < FRESH_TOKEN_SECONDS
+      end
+    end
+    private_constant :OAuth2Refresh
+  end
+end

data/lib/x/core/oauth2_tokens.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "credential_validator"
+require_relative "setting_validator"
+require_relative "errors/unsupported_format"
+
+module X
+  module Core
+    # The OAuth 2.0 tokens one refresh issued, or the exchange of an authorization code, which save_tokens is
+    # passed to store
+    #
+    # It is frozen, and taken while the refresh holds its lock, so it holds the tokens of the refresh it reports,
+    # whatever refreshes follow on other threads, where the authenticator holds the tokens of the latest one.
+    #
+    # @api public
+    class ::X::OAuth2Tokens
+      # The number of the format of the state Marshal writes, which every release of 1.x writes
+      #
+      # A later release of 1.x adds to the state only what an earlier one ignores, parts after those it reads and keys of a
+      # Hash it does not read, so that the state one release of 1.x writes is read by every other, earlier or later.
+      MARSHAL_FORMAT = 1
+      private_constant :MARSHAL_FORMAT
+
+      # The message of the error raised for a token that is not a String
+      NOT_A_STRING = "%s must be a String, not a %s"
+      private_constant :NOT_A_STRING
+      # The message of the error raised for a token that is neither a String nor nil
+      NOT_A_STRING_OR_NIL = "%s must be a String or nil, not a %s"
+      private_constant :NOT_A_STRING_OR_NIL
+      # The message of the error raised for JSON that is not an object
+      NOT_AN_OBJECT = "the JSON of X::OAuth2Tokens must be an object, not a %s"
+      private_constant :NOT_AN_OBJECT
+      # The message of the error raised for an expiration time in JSON that is neither a String nor nil
+      NOT_A_TIME_STRING = "the expires_at of the JSON of X::OAuth2Tokens must be an ISO 8601 String or nil, not a %s"
+      private_constant :NOT_A_TIME_STRING
+      # The digits of a second the JSON of an expiration time holds, as many as a Time holds, so it reads back equal
+      FRACTION_DIGITS = 9
+      private_constant :FRACTION_DIGITS
+
+      # Read tokens back from the JSON that to_json wrote, or the Hash that as_json gave
+      #
+      # A store that holds JSON, such as Redis or a JSON column, holds the tokens as as_json gives them: the number of
+      # their format, each token, and the expiration time as an ISO 8601 String, which this reads back as a Time. The
+      # Hash may be keyed by Symbol, as JSON.parse(json, symbolize_names: true) and many caches give it back.
+      #
+      # @api public
+      # @param json [String, Hash{String, Symbol => Object}] the JSON to_json wrote, or the Hash as_json gave
+      # @return [OAuth2Tokens] the frozen tokens
+      # @raise [JSON::ParserError] if the String is not JSON
+      # @raise [ArgumentError] if the JSON is not an object, its expiration time is not an ISO 8601 String or nil, or
+      #   its tokens or scopes are not those the constructor takes
+      # @raise [UnsupportedFormat] if the JSON is of a format this release does not read
+      # @example Read tokens stored as JSON
+      #   X::OAuth2Tokens.from_json(redis.get("tokens"))
+      def self.from_json(json)
+        state = json_state(json)
+        new(access_token: state["access_token"], refresh_token: state["refresh_token"],
+          expires_at: json_time(state["expires_at"]), scopes: state["scopes"])
+      end
+
+      # The Hash of the JSON of tokens, of the format this release reads
+      #
+      # @api private
+      # @param json [String, Hash{String, Symbol => Object}] the JSON to_json wrote, or the Hash as_json gave
+      # @return [Hash{String => Object}] the Hash, keyed by String
+      # @raise [ArgumentError] if the JSON is not an object
+      # @raise [UnsupportedFormat] if the JSON is of a format this release does not read
+      def self.json_state(json)
+        state = json.is_a?(String) ? JSON.parse(json) : json
+        raise ArgumentError, format(NOT_AN_OBJECT, state.class) unless state.is_a?(Hash)
+
+        state = state.transform_keys(&:to_s)
+        format = state["format"]
+        raise UnsupportedFormat, "#{self} reads format #{MARSHAL_FORMAT} of JSON, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)
+
+        state
+      end
+
+      # The expiration time the JSON of tokens holds as an ISO 8601 String
+      #
+      # @api private
+      # @param expires_at [String, nil] the expiration time as JSON holds it
+      # @return [Time, nil] the expiration time, or nil for tokens that hold none
+      # @raise [ArgumentError] if the expiration time is neither an ISO 8601 String nor nil
+      def self.json_time(expires_at)
+        return if expires_at.nil?
+        raise ArgumentError, format(NOT_A_TIME_STRING, expires_at.class) unless expires_at.is_a?(String)
+
+        Time.iso8601(expires_at)
+      end
+      private_class_method :json_state, :json_time
+
+      # The OAuth 2.0 access token the refresh issued
+      # @api public
+      # @return [String] the access token
+      # @example Get the access token
+      #   tokens.access_token
+      attr_reader :access_token
+
+      # The OAuth 2.0 refresh token the refresh issued
+      #
+      # It is the refresh token the refresh was sent with when X issued none. An authorization without the
+      # offline.access scope issues none, so the tokens of its exchange hold nil, and the access token acts for the
+      # user until it expires, with nothing to refresh it.
+      #
+      # @api public
+      # @return [String, nil] the refresh token, or nil for tokens issued without one
+      # @example Get the refresh token
+      #   tokens.refresh_token
+      attr_reader :refresh_token
+
+      # The time the access token expires, or nil when the refresh reported no lifetime
+      # @api public
+      # @return [Time, nil] the expiration time
+      # @example Get the expiration time
+      #   tokens.expires_at
+      attr_reader :expires_at
+
+      # The scopes X granted the access token
+      #
+      # They are the scopes the user authorized, which may be fewer than the app asked for, since a user can leave
+      # some out on the consent screen, so an app that needs a scope checks for it here rather than learn of it from
+      # the 403 Forbidden of a request. A refresh that names no scopes keeps those it refreshed, as OAuth 2.0 has it.
+      #
+      # @api public
+      # @return [Array<String>, nil] the scopes, frozen, or nil when X named none and none were known
+      # @example Check that the user let the app post
+      #   tokens.scopes.include?("tweet.write")
+      attr_reader :scopes
+
+      # Initialize the tokens of a refresh
+      #
+      # @api public
+      # @param access_token [String] the access token
+      # @param refresh_token [String, nil] the refresh token, or nil for tokens issued without one
+      # @param expires_at [Time, nil] the expiration time of the access token
+      # @param scopes [Array<String>, nil] the scopes X granted the access token, or nil when they are not known
+      # @return [OAuth2Tokens] the frozen tokens
+      # @raise [ArgumentError] if the access token is not a String, the refresh token neither a String nor nil, or a
+      #   token is empty, or if the expiration time is neither a Time nor nil, as it is a String for tokens read back
+      #   from JSON other than with from_json, or the scopes are neither an Array of Strings that each name a scope nor
+      #   nil
+      # @example Build the tokens of a refresh
+      #   X::OAuth2Tokens.new(access_token: "token", refresh_token: "refresh", expires_at: Time.now + 7200,
+      #     scopes: %w[tweet.read users.read offline.access])
+      def initialize(access_token:, refresh_token: nil, expires_at: nil, scopes: nil)
+        raise ArgumentError, format(NOT_A_STRING, :access_token, access_token.class) if access_token.nil?
+        raise ArgumentError, format(NOT_A_STRING_OR_NIL, :refresh_token, refresh_token.class) unless refresh_token.nil? || refresh_token.is_a?(String)
+
+        CredentialValidator.validate_required!({access_token:}, {refresh_token:, expires_at:, scopes:})
+        @access_token = SettingValidator.frozen(access_token)
+        @refresh_token = SettingValidator.frozen(refresh_token)
+        @expires_at = expires_at
+        @scopes = CredentialValidator.frozen_scopes(scopes)
+        freeze
+      end
+
+      # The tokens as a Hash, to store, and to build a client of
+      #
+      # Its keys are keywords X::Client.new and X::OAuth2Authenticator.new take, so that the tokens build a client, as
+      # in X::Client.new(client_id:, **tokens.to_h), and a later release of 1.x adds a key to it only as both take it.
+      #
+      # @api public
+      # @return [Hash{Symbol => String, Time, Array<String>, nil}] the access token, refresh token, expiration time,
+      #   and scopes
+      # @example Store the tokens
+      #   store.save(**tokens.to_h)
+      def to_h = {access_token:, refresh_token:, expires_at:, scopes:}
+
+      # Check whether other tokens are the same tokens
+      #
+      # @api public
+      # @param other [Object] the other tokens
+      # @return [Boolean] true if the other tokens are of the same class, with the same values
+      # @example Compare tokens
+      #   tokens == other
+      def ==(other) = other.instance_of?(self.class) && to_h.eql?(other.to_h)
+      alias_method :eql?, :==
+
+      # The hash of the tokens, for use as a Hash key
+      #
+      # @api public
+      # @return [Integer] the hash
+      # @example Get the hash
+      #   tokens.hash
+      def hash = [self.class, to_h].hash
+
+      # The tokens as JSON writes them, led by the number of their format
+      #
+      # JSON holds no Time, so the expiration time is written as an ISO 8601 String in UTC, to the nanosecond, which
+      # from_json reads back as a Time equal to it. It holds the tokens themselves, since tokens are written as JSON to
+      # be stored, so what JSON wrote is kept as secret as the tokens are.
+      #
+      # @api public
+      # @return [Hash{String => Integer, String, Array<String>, nil}] the number of the format, the access token, refresh
+      #   token, expiration time, and scopes
+      # @example Store the tokens of a refresh in Redis
+      #   X::Client.new(**credentials, save_tokens: ->(tokens) { redis.set("tokens", tokens.to_json) })
+      def as_json(*)
+        {"format" => MARSHAL_FORMAT, "access_token" => access_token, "refresh_token" => refresh_token,
+         "expires_at" => expires_at&.getutc&.iso8601(FRACTION_DIGITS), "scopes" => scopes}
+      end
+
+      # The tokens as JSON, which from_json reads back
+      #
+      # @api public
+      # @param state [JSON::State, nil] the state a JSON encoder passes, which the Hash of as_json is given
+      # @return [String] the tokens as a JSON object
+      # @example Store the tokens of a refresh in Redis
+      #   X::Client.new(**credentials, save_tokens: ->(tokens) { redis.set("tokens", tokens.to_json) })
+      def to_json(state = nil) = as_json.to_json(state)
+
+      # Summarize the tokens for the console without revealing them
+      #
+      # @api public
+      # @return [String] the class name and expiration time
+      # @example Inspect tokens
+      #   tokens.inspect # => #<X::OAuth2Tokens expires_at=nil>
+      def inspect = "#<#{self.class} expires_at=#{expires_at.inspect}>"
+
+      # The state Marshal writes
+      #
+      # What is written is plain data, led by the number of its format, so that tokens written by one release of 1.x are
+      # read by a later one: the tokens, their expiration time, and their scopes, as to_h gives them. It holds the tokens themselves,
+      # since tokens are marshalled to be stored, so what Marshal wrote is kept as secret as the tokens are.
+      #
+      # @api public
+      # @return [Array(Integer, Hash{Symbol => String, Time, Array<String>, nil})] the number of the format, then the
+      #   tokens as a Hash
+      # @example Store the tokens of a refresh
+      #   X::Client.new(**credentials, save_tokens: ->(tokens) { File.binwrite("tokens", Marshal.dump(tokens)) })
+      def marshal_dump = [MARSHAL_FORMAT, to_h]
+
+      # Restore tokens Marshal read, built as the constructor builds them, frozen
+      #
+      # @api public
+      # @param state [Array] the state Marshal wrote
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read stored tokens
+      #   Marshal.load(File.binread("tokens")).expires_at
+      def marshal_load(state)
+        format, tokens = state #: [Integer, {access_token: String, refresh_token: String?, expires_at: Time?, scopes: Array[String]?}]
+        raise UnsupportedFormat, "#{self.class} reads format #{MARSHAL_FORMAT} of Marshal, not #{format.inspect}" unless MARSHAL_FORMAT.eql?(format)
+
+        initialize(**tokens.slice(:access_token, :refresh_token, :expires_at, :scopes)) # steep:ignore InsufficientKeywordArguments
+      end
+
+      # Write the state Marshal writes as YAML
+      #
+      # YAML would write the instance variables of the tokens, and read them back into tokens that are not frozen, so
+      # they say how they are written: the number of their format, then each of them, under the name to_h gives it.
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML writes the tokens with
+      # @return [void]
+      # @example Write tokens as YAML
+      #   YAML.dump(tokens)
+      def encode_with(coder)
+        coder["format"] = MARSHAL_FORMAT
+        to_h.each { |key, value| coder[key.to_s] = value }
+      end
+
+      # Restore tokens YAML read, frozen, as Marshal restores them
+      #
+      # @api public
+      # @param coder [Psych::Coder] the coder YAML read the tokens with
+      # @return [void]
+      # @raise [UnsupportedFormat] if the state is of a format this release does not read
+      # @example Read tokens written as YAML
+      #   YAML.unsafe_load(File.read("tokens.yml")).expires_at
+      def init_with(coder) = marshal_load([coder["format"], coder.map.transform_keys(&:to_sym)])
+    end
+  end
+end

data/lib/x/core/origin.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "authenticator"
+
+module X
+  module Core
+    # The origin a request is sent to, and the credentials it carries there
+    #
+    # Credentials are for the origin they were given for: the scheme, host, and port of the base URL of a client.
+    # A request to any other origin carries none of them, whether it was a redirect followed there or an endpoint
+    # that named a whole URL, since the credentials of the API are no business of another host. What is dropped is
+    # the authenticator, which signs the Authorization header of a request, and any Authorization, Cookie, or
+    # Proxy-Authorization header of the client or the request itself.
+    #
+    # Internal to x-core: Client and RedirectHandler decide with it what a request carries.
+    #
+    # @api private
+    module Origin
+      extend self
+
+      # The headers that carry credentials, which a request to another origin drops
+      CREDENTIAL_HEADERS = [Authenticator::AUTHENTICATION_HEADER, "Cookie", "Proxy-Authorization"].freeze
+
+      # The authenticator and headers a request carries to an origin
+      #
+      # The credentials that would leave the origin they were given for are dropped.
+      #
+      # @api private
+      # @param from [URI::Generic] the URI the credentials were given for, such as the base URL of a client
+      # @param to [URI::Generic] the URI the request is sent to
+      # @param authenticator [Authenticator] the authenticator of the request
+      # @param headers [Hash{String => String}] the headers of the request
+      # @return [Array(Authenticator, Hash{String, Symbol => String})] the authenticator that signs the request,
+      #   and the headers it is sent with
+      # @example Keep the credentials of a request to the API
+      #   X::Core::Origin.credentials_for(from: URI(client.base_url), to: uri, authenticator:, headers:)
+      def credentials_for(from:, to:, authenticator:, headers:)
+        return [authenticator, headers] if same?(from, to)
+
+        [Authenticator.new, without_credentials(headers)]
+      end
+
+      # Check whether two URIs share a scheme, host, and port
+      #
+      # @api private
+      # @param uri [URI::Generic] the one URI
+      # @param other [URI::Generic] the other URI
+      # @return [Boolean] true if both have the same origin
+      # @example Check whether an endpoint names the host of the base URL
+      #   X::Core::Origin.same?(URI(client.base_url), uri)
+      def same?(uri, other) = of(uri).eql?(of(other))
+
+      # Check whether the response an error was raised for came from an origin
+      #
+      # A request answered by the origin its credentials were given for carried them, and one answered by another,
+      # after a redirect there, carried none, so only a rejection by that origin rejected them.
+      #
+      # @api private
+      # @param error [HTTPError] the error
+      # @param origin [URI::Generic] a URI of the origin
+      # @return [Boolean] true if the response came from the origin, and false for one that names no URI
+      # @example Check whether a rejection came from the base URL of a client
+      #   X::Core::Origin.answered?(error, URI(client.base_url))
+      def answered?(error, origin)
+        uri = error.http_response.uri
+        !uri.nil? && same?(origin, uri)
+      end
+
+      private
+
+      # The scheme, host, and port of a URI, in lowercase
+      # @api private
+      # @param uri [URI::Generic] the URI
+      # @return [Array(String, String, Integer)] the origin
+      def of(uri)
+        normalized = uri.normalize
+        [normalized.scheme, normalized.host, normalized.port]
+      end
+
+      # Headers without the ones that carry credentials
+      #
+      # Authorization, Cookie, and Proxy-Authorization are dropped, whatever their case, whether a String or a Symbol
+      # names them.
+      #
+      # @api private
+      # @param headers [Hash{String => String}] the headers
+      # @return [Hash{String => String}] the headers that carry no credentials
+      def without_credentials(headers)
+        headers.reject { |name, _| CREDENTIAL_HEADERS.any? { |header| name.casecmp?(header) } }
+      end
+    end
+    private_constant :Origin
+  end
+end