end_point_blank 0.6.0 → 0.12.0

data/lib/end_point_blank/commands/generate_access_token.rb

@@ -2,34 +2,267 @@
 
 require 'excon'
 require "json"
+require "openssl"
+require "socket"
+require "timeout"
 require_relative 'http'
+require_relative "../configuration_error"
+require_relative "../target_url"
 
 module EndPointBlank
   module Commands
+    # The outcome of one attempt to mint an access token, with enough of the
+    # intake's answer attached that a caller can decide what to do about it.
+    #
+    # intake's access-token endpoint answers 201 on success, 400 for a bad
+    # request (an invalid token_ttl, a missing base_url), 401 for a rejected
+    # credential, 422 when the target or source application cannot be resolved
+    # or the mint itself failed, and 5xx for a genuine fault. Those are not
+    # interchangeable: 401 needs the credential re-issued, 400/422 need the
+    # request or the registration fixed, and 5xx or a dead socket just needs
+    # trying again. Collapsing them -- which is what returning a bare Hash or
+    # nil does -- is what made every failure look the same to a caller.
+    #
+    # A Data is deeply appropriate here: it is immutable and frozen, so a
+    # result can be handed across threads, cached, or logged without anyone
+    # being able to edit the verdict after the fact.
+    AccessTokenResult = Data.define(:outcome, :status, :payload) do
+      # A token really was minted: a 2xx whose body parsed and carries both a
+      # non-empty token and the non-empty base_url to cache it under. Nothing
+      # else is a success, so a caller that branches on this can read the
+      # token straight off the payload without checking again that there is
+      # one -- and a check that is not there is a check nobody can forget.
+      def success?
+        outcome == :success
+      end
+
+      # 401. Permanent until the API credential itself changes.
+      def credential_rejected?
+        outcome == :credential_rejected
+      end
+
+      # Any other 4xx -- in practice intake's 400 and 422. Permanent too, but
+      # the credential is fine; the request or the registration is not.
+      def request_rejected?
+        outcome == :request_rejected
+      end
+
+      # 5xx, any other unexpected non-2xx, and a 2xx that carried nothing
+      # usable -- unreadable, or missing the token, or missing the base_url
+      # there is no way to cache a token without. Empty counts as missing;
+      # see .usable_string?.
+      def server_error?
+        outcome == :server_error
+      end
+
+      # No answer at all: timeout, refused connection, DNS failure -- any
+      # case where no usable HTTP status was obtained. Transient.
+      #
+      # Note what is NOT here: a body we could not read. That is classified
+      # by the status that carried it, because the status is the part with
+      # the remedy in it.
+      def transport_error?
+        outcome == :transport_error
+      end
+
+      # The direct complement of #success?, and deliberately the only
+      # predicate here that spans more than one outcome. There is no
+      # #retriable? on purpose: a single retry/no-retry boolean would fold
+      # five honest names back into two, and it is one more thing that can
+      # answer wrongly for a 400 or a 422. A caller that wants a retry policy
+      # writes it against the outcome it can see.
+      def failure?
+        !success?
+      end
+
+      # True when payload carries everything a mint needs: a token, and the
+      # base URL to cache it under.
+      #
+      # The single definition of what counts as a mint, and it sits here next
+      # to the outcomes rather than in the cache that consumes them, so a
+      # second layer cannot form its own opinion and end up disagreeing with
+      # the outcome it was handed. EndPointBlank::AccessTokens asks this
+      # instead of re-deriving it, and words its failure log line from the
+      # same predicate.
+      def self.minted?(payload)
+        payload.is_a?(Hash) && usable_string?(payload[:token]) && usable_string?(payload[:base_url])
+      end
+
+      # True when value is something there is actually anything to be had
+      # from.
+      #
+      # Spelled out rather than left to a bare `payload[:token] &&`, which is
+      # what this replaced: "" is truthy in Ruby, so an empty token sailed
+      # through as a success, and an empty base_url became a cache key no
+      # lookup could ever match. Neither is ever legitimate -- intake's token
+      # and base_url are both NOT NULL -- so either one means a broken server.
+      def self.usable_string?(value)
+        value.is_a?(String) && !value.empty?
+      end
+    end
+
     module GenerateAccessTokenMethods
+      # What a request that never completed raises: Excon's own errors (its
+      # timeouts and socket failures among them), and the socket, SSL and
+      # timeout errors underneath, in case one arrives unwrapped. Only these
+      # are a :transport_error.
+      TRANSPORT_ERRORS = [
+        Excon::Error, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Timeout::Error
+      ].freeze
+
       module ClassMethods
         def configuration
           EndPointBlank::Configuration.instance
         end
 
+        # Mint an access token, reporting what actually happened.
+        #
+        # @param base_url [String] the URL a token is wanted for. Its
+        #   userinfo, query and fragment are never sent ({TargetUrl.strip}).
+        # @return [AccessTokenResult] never nil. A URL that cannot be parsed
+        #   into an http or https URL with a host is :request_rejected with no
+        #   status, and nothing is sent.
+        # @raise [ConfigurationError] when client_id or client_secret is
+        #   missing; nothing is sent.
+        # @raise [StandardError] anything raised while minting that is not
+        #   one of {TRANSPORT_ERRORS}; see the rescue below.
+        def token_result(base_url) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          # Defensive: AccessTokens already strips, but this is callable on
+          # its own and must not put a raw URL in the request body either.
+          target = TargetUrl.strip(base_url)
+          if target.nil?
+            EndPointBlank.logger.error "Access token not requested: the URL could not be parsed " \
+                                       "into an http or https URL with a host (not shown)"
+            return AccessTokenResult.new(outcome: :request_rejected, status: nil, payload: nil)
+          end
+
+          response = post_token_request(target)
+
+          status = response.status
+          EndPointBlank.logger.info "Authentication response: #{status}"
+
+          # parse_payload never raises, so nothing between here and the
+          # classification can throw away a status we already hold.
+          payload = parse_payload(response.body)
+
+          # The invariant, enforced in exactly one place: :transport_error
+          # means no usable HTTP status was obtained. Anything that is not a
+          # real status code leaves here rather than reaching classification,
+          # so no other branch has to keep re-deciding what a missing status
+          # means. The payload still rides along, because `token` below is
+          # published API and has always handed back whatever it could parse.
+          return transport_error(payload) unless status.is_a?(Integer)
+
+          AccessTokenResult.new(outcome: outcome_for(status, payload), status: status, payload: payload)
+        rescue ConfigurationError
+          # Missing client credentials are not a transport error: nothing was
+          # sent, and retrying cannot help. Let it be seen (sc-1469).
+          raise
+        rescue *TRANSPORT_ERRORS => e
+          # Reached only when the request never completed, so there is no
+          # status to classify on. Anything else raised above is a bug, not
+          # an unreachable intake, and calling it a transport error would
+          # send the reader off to check the network: it propagates, and
+          # Authorization.header reports it as "the token request failed
+          # unexpectedly" with the exception as its cause (sc-1469).
+          EndPointBlank.logger.error "Error occurred during authentication: #{e.message}\n #{e.backtrace.join("\n")}"
+          transport_error
+        end
+
+        # Mint an access token.
+        #
+        # The body-or-nil accessor, where a body means a token was actually
+        # minted. Anything else answers nil: a 401 or 422 whose body explains
+        # the refusal, and a 2xx that parsed into something with no usable
+        # token in it.
+        #
+        # Returning those bodies would hand the caller a truthy value for a
+        # request that produced no token -- the failure {token_result} exists
+        # to remove, one layer down. Nothing is lost:
+        # `token_result(base_url).payload` is exactly what this used to
+        # return, now alongside the outcome that explains it.
+        #
+        # @param base_url [String] the URL a token is wanted for.
+        # @return [Hash, nil] symbol-keyed response body when a token was
+        #   minted, otherwise nil.
+        # @raise [StandardError] whatever {token_result} raises, as itself.
         def token(base_url)
+          result = token_result(base_url)
+
+          result.success? ? result.payload : nil
+        end
+
+        private
+
+        def post_token_request(base_url)
           body = {base_url: base_url}
           if configuration.token_ttl
             body[:token_ttl] = configuration.token_ttl
           end
-          auth = Authorization.header
-          response = Excon.post(configuration.access_token_url,
-            headers: {'Authorization' => auth, 'Content-Type' => 'application/json'},
+          auth = Authorization.intake_header
+          Excon.post(configuration.access_token_url,
+            headers: EndPointBlank::Commands::Http.headers(auth),
             body: body.to_json,
             **EndPointBlank::Commands::Http::TIMEOUT_OPTIONS
           )
-          EndPointBlank.logger.info "Authentication response: #{response.status}"
-          parsed_body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
-          parsed_body.transform_keys(&:to_sym)
-        rescue => e
-          EndPointBlank.logger.error "Error occurred during authentication: #{e.message}\n #{e.backtrace.join("\n")}"
+        end
+
+        def transport_error(payload = nil)
+          AccessTokenResult.new(outcome: :transport_error, status: nil, payload: payload)
+        end
+
+        # Returns the symbolized body, or nil when it cannot be read. Total:
+        # it never raises, deliberately, so that a body it cannot make sense
+        # of can never cost us the status that body arrived under.
+        #
+        # A body we cannot parse is still reported rather than swallowed:
+        # before this, one blanket `rescue` turned a JSON::ParserError into
+        # the same silent nil as a dead socket. The message keeps its original
+        # prefix so any log alerting built on the old line still matches.
+        def parse_payload(body)
+          parsed = body.is_a?(String) ? JSON.parse(body) : body
+          parsed.transform_keys(&:to_sym)
+        rescue StandardError => e
+          EndPointBlank.logger.error "Error occurred during authentication: #{e.message} (response body was not JSON)"
           nil
         end
+
+        # Classify on the HTTP status FIRST; the body only ever refines the
+        # answer, and only for a 2xx.
+        #
+        # :transport_error means exactly one thing -- no usable HTTP status
+        # was obtained -- so it is not reachable from here. Do not
+        # reintroduce parse-first classification: a 401 whose body will not
+        # parse is still a rejected credential, and filing it under a name
+        # that reads as transient invites the forever-retry this exists to
+        # end. That is not hypothetical. The SDK
+        # reaches intake through Caddy, and any proxy, WAF or ALB in front of
+        # the app can answer 401 with an HTML error page intake never
+        # generated -- the credential really is rejected and the body really
+        # is unparseable, at the same time.
+        #
+        # The one thing the body decides, and only ever on a 2xx: whether a
+        # token was actually minted. A 2xx that is unreadable, or carries no
+        # token, or a token with no base_url to cache it under, is a broken
+        # server, and it is truthful to say so with the real 2xx status
+        # attached -- intake's base_url is NOT NULL and it answers 422 rather
+        # than minting when the URL resolves to nothing, so a 2xx without one
+        # cannot be anything else.
+        #
+        # Calling such a response a success instead would hand back a result
+        # whose #success? is true and whose token is absent, leaving every
+        # caller a re-check to remember -- which is exactly the check that
+        # gets forgotten. The payload rides along on the failure either way,
+        # so the specific reason survives for the log line and `token` still
+        # answers with precisely the body it always did.
+        def outcome_for(status, payload)
+          case status
+          when 200..299 then AccessTokenResult.minted?(payload) ? :success : :server_error
+          when 401 then :credential_rejected
+          when 400..499 then :request_rejected
+          else :server_error # 5xx, and any 3xx, which Excon does not follow.
+          end
+        end
       end
 
       def self.included(base)

data/lib/end_point_blank/commands/http.rb

@@ -1,4 +1,5 @@
 require 'excon'
+require_relative '../version'
 
 module EndPointBlank
   module Commands
@@ -16,13 +17,31 @@ module EndPointBlank
       # Merge this into any `Excon.post`/`Excon.new` call in the lib.
       TIMEOUT_OPTIONS = { connect_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT }.freeze
 
+      # The x-epb-sdk value sent on every call to intake: ruby/<version>, the
+      # version of this gem as loaded (sc-1463). intake ignores it today; it is
+      # there so intake can record the oldest version seen per credential for
+      # the move gate. That gate's minimum Ruby version is the release that
+      # turns derive_base_url_from_client_id on by default, not the one that
+      # added this header: with the option at its default, this version keeps
+      # calling in.endpointblank.com after its organization moves.
+      def self.sdk_header
+        "ruby/#{EndPointBlank::VERSION}"
+      end
+
+      # The headers for every call to intake. Use this for any
+      # `Excon.post`/`Excon.new` call in the lib, so x-epb-sdk cannot be left
+      # off one of them.
+      def self.headers(auth)
+        { 'Authorization' => auth, 'Content-Type' => 'application/json', 'x-epb-sdk' => sdk_header }
+      end
+
       def self.post(url, auth, body)
         attempt = 0
         begin
           attempt += 1
           Excon.post(
             url,
-            headers: { 'Authorization' => auth, 'Content-Type' => 'application/json' },
+            headers: headers(auth),
             body: body.to_json,
             **TIMEOUT_OPTIONS
           )

data/lib/end_point_blank/configuration.rb

@@ -11,19 +11,108 @@ module EndPointBlank
   class Configuration
     include Singleton
 
+    # Seconds an authorization decision stays cached when cache_ttl is never
+    # assigned. See {#cache_ttl=}.
+    DEFAULT_CACHE_TTL = 300
+
+    DEFAULT_BASE_URL = "https://in.endpointblank.com"
+
+    # sc-1463: an organization's intake answers at
+    # https://<slug>.in.endpointblank.com. See {#base_url}.
+    DERIVED_BASE_URL_SUFFIX = ".in.endpointblank.com"
+
+    # app_portal's Organizations.Slug.valid?/1: a domain label of up to 20
+    # [a-z0-9-] characters that starts and ends alphanumeric, then "-" and 6
+    # random characters. Copied, not loosened.
+    CLIENT_ID_SLUG = /\A[a-z0-9](?:[a-z0-9-]{0,18}[a-z0-9])?-[a-z0-9]{6}\z/
+
     attr_writer :client_id, :client_secret, :base_url, :log_base_url, :app_name, :env_name
 
     attr_accessor :worker_count, :log_mode,
-                  :version_finder, :application_version, :token_ttl, :cache_ttl,
+                  :version_finder, :application_version, :token_ttl,
                   :masking_rules, :mask_hook, :logger, :trust_proxy_headers
 
+    attr_reader :cache_ttl, :derive_base_url_from_client_id
+
     def initialize
       @worker_count = 4
       @token_ttl = nil
-      @cache_ttl = 300
+      self.cache_ttl = DEFAULT_CACHE_TTL
       @masking_rules = []
       @mask_hook = nil
       @trust_proxy_headers = true
+      @derive_base_url_from_client_id = false
+    end
+
+    # Sets the authorization decision cache's TTL, in whole seconds.
+    #
+    # sc-970 sets one rule for this setting across every EndPointBlank SDK:
+    #
+    # - never assigned: the default, {DEFAULT_CACHE_TTL} (300) seconds;
+    # - 0: the cache is disabled;
+    # - a positive Integer: that many seconds;
+    # - anything else -- an explicit nil, a negative number, or a non-Integer
+    #   such as "300" or 3.5 -- raises ArgumentError here, at configure time,
+    #   and leaves the previous value in place. It is never deferred to the
+    #   first cache read or store, and never quietly read as "disabled" or
+    #   as "use the default".
+    #
+    # @raise [ArgumentError] if value is not a non-negative Integer
+    def cache_ttl=(value)
+      unless value.is_a?(Integer) && !value.negative?
+        raise ArgumentError,
+              "EndPointBlank::Configuration#cache_ttl must be a non-negative Integer number of " \
+              "seconds, got #{value.inspect}. To use the default of #{DEFAULT_CACHE_TTL} seconds, " \
+              "omit the cache_ttl setting entirely; set it to 0 to disable the cache."
+      end
+
+      @cache_ttl = value
+    end
+
+    # Whether {#base_url} may derive the intake hostname from a slug-prefixed
+    # {#client_id} when no base URL is set (sc-1463). Defaults to false,
+    # because *.in.endpointblank.com has no DNS or TLS in production yet; it
+    # will default to true in a later release.
+    #
+    # Only true or false: a String "true" from an env var must not quietly
+    # leave derivation off, and nothing else has a sensible reading. Like
+    # {#cache_ttl=}, anything else raises here, at configure time, and
+    # leaves the previous value in place.
+    #
+    # @raise [ArgumentError] if value is not true or false
+    def derive_base_url_from_client_id=(value)
+      unless [true, false].include?(value)
+        raise ArgumentError,
+              "EndPointBlank::Configuration#derive_base_url_from_client_id must be true or false, " \
+              "got #{value.inspect}."
+      end
+
+      @derive_base_url_from_client_id = value
+    end
+
+    # The organization slug a client_id names, or nil for one without it
+    # (issued before sc-1463).
+    #
+    # The same rule as app_portal's Credentials.client_id_slug/1 and every
+    # other EndPointBlank SDK: the part before the first "." must have the
+    # exact shape of an organization slug, and something must follow the
+    # dot. "Contains a ." is not enough, because app_portal has always
+    # accepted a typed client_id, so a legacy "my.client" can exist and must
+    # keep calling the default intake.
+    #
+    # @param client_id [Object] anything; only a String can carry a slug
+    # @return [String, nil]
+    def self.client_id_slug(client_id)
+      return nil unless client_id.is_a?(String)
+      # Total, like Elixir's: split and match? raise on invalid bytes or on an
+      # encoding that is not ASCII-compatible (UTF-16), and neither can be a
+      # credential that authenticates.
+      return nil unless client_id.valid_encoding? && client_id.encoding.ascii_compatible?
+
+      slug, random = client_id.split(".", 2)
+      return nil if random.nil? || random.empty?
+
+      CLIENT_ID_SLUG.match?(slug) ? slug : nil
     end
 
     # Returns the configured client id, falling back to the
@@ -39,9 +128,11 @@ module EndPointBlank
     end
 
     # Returns the configured base URL, falling back to the
-    # ENDPOINTBLANK_BASE_URL environment variable, then a built-in default.
+    # ENDPOINTBLANK_BASE_URL environment variable, then -- only while
+    # {#derive_base_url_from_client_id} is on -- the hostname derived from a
+    # slug-prefixed {#client_id}, then a built-in default.
     def base_url
-      @base_url || ENV["ENDPOINTBLANK_BASE_URL"] || "https://in.endpointblank.com"
+      @base_url || ENV["ENDPOINTBLANK_BASE_URL"] || derived_base_url || DEFAULT_BASE_URL
     end
 
     # Returns the configured log base URL, falling back to the
@@ -104,5 +195,21 @@ module EndPointBlank
     def env_name
       @env_name || ENV["ENDPOINTBLANK_ENV"]
     end
+
+    private
+
+    # sc-1463: a new client_id is "<organization slug>.<random>", and that
+    # organization's intake answers at https://<slug>.in.endpointblank.com.
+    # Only while derive_base_url_from_client_id is on: *.in.endpointblank.com
+    # has no DNS or TLS in production yet, so it defaults off, and off means
+    # today's default for every client_id. Logs are not derived: whether they
+    # get a per-organization hostname is still open, so log_base_url keeps its
+    # own default.
+    def derived_base_url
+      return nil unless @derive_base_url_from_client_id == true
+
+      slug = self.class.client_id_slug(client_id)
+      slug && "https://#{slug}#{DERIVED_BASE_URL_SUFFIX}"
+    end
   end
 end

data/lib/end_point_blank/configuration_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  # Reopened with the same superclass in end_point_blank.rb; declared here too
+  # so this file can be required on its own.
+  class Error < StandardError; end
+
+  # Raised when a setting the SDK cannot work without is missing -- today, a
+  # nil or empty client_id or client_secret when the SDK builds the Basic
+  # header for a call to its own intake.
+  #
+  # Loud on purpose (sc-1469). Before sc-1469 the header was built with
+  # `client_id + ":" + client_secret`, which raised on a nil; interpolation
+  # does not, and would quietly send `Basic Og==` (base64 of ":") on every
+  # call, which intake rejects as a bad credential -- a misconfiguration
+  # dressed up as a revoked one.
+  class ConfigurationError < Error; end
+end

data/lib/end_point_blank/rails/authenticated.rb

@@ -2,20 +2,75 @@ require "active_support/concern"
 
 module EndPointBlank
   module Rails
+    # Installs a `before_action :authenticate!` that asks intake whether the
+    # calling credential may reach this controller at all, refusing the request
+    # with an `UnauthorizedError` when it may not.
+    #
+    # == Why this concern exists rather than being deleted
+    #
+    # Until now it could not have worked once: it called
+    # `EndPointBlank::Commands::EndpointAuthenticate`, a constant that has never
+    # been defined anywhere in this gem, so every action of every controller
+    # including it raised `NameError` before authentication could succeed or
+    # fail. Nothing in this project included it, and the one test-application
+    # controller named for it (`epb_test_rails`'s `AuthenticatedController`)
+    # actually includes `Authorized`, so nothing ever noticed.
+    #
+    # That made "implement or delete" a real question. It is implemented,
+    # because the authenticate path is not a Rails-only idea that Rails
+    # happened not to need: the JS, Java and Python SDKs each expose one, and
+    # each of their commands documents itself as "equivalent to the Ruby gem's
+    # `EndPointBlank::Commands::BasicAuthenticate`". Three SDKs were ported
+    # from a Ruby original that was here the whole time and simply never wired
+    # up. (Elixir has no authenticate path at all, so "four other SDKs expose
+    # one", as sc-306 puts it, is three -- but three of three name this gem.) A
+    # missing authenticate path in Ruby is a gap, not a decision.
+    #
+    # == Why `BasicAuthenticate` and not a new `EndpointAuthenticate`
+    #
+    # Writing a `Commands::EndpointAuthenticate` to satisfy the old call site
+    # would have invented a second command for a job this gem already has a
+    # command for, and left `BasicAuthenticate` -- required by `end_point_blank.rb`,
+    # ported into three other SDKs, and carrying the request body shape intake
+    # actually reads -- dead in the tree next to it. Nothing can be depending on
+    # the name `EndpointAuthenticate`, because it never resolved; no public
+    # constant is being removed here, only one that was never there is being
+    # left absent.
+    #
+    # == Deliberately no cache
+    #
+    # `Authorized` caches intake's answer per credential/route/method/version.
+    # This path does not, matching every other SDK's authenticate command.
+    # Adding one here would be a behaviour change none of the four share and
+    # neither story asked for; it belongs in its own story if it is wanted.
     module Authenticated
-     extend ActiveSupport::Concern
+      extend ActiveSupport::Concern
 
       included do
         before_action :authenticate!
       end
 
       def authenticate!
-        result = EndPointBlank::Commands::EndpointAuthenticate.authenticate(request)
-        result_json = JSON.parse(result.body)
-        if !result || result.status != 201
-          raise UnauthorizedError, "Authentication failed: #{result_json['error']}"
-        end
+        result = EndPointBlank::Commands::BasicAuthenticate.authenticate(request)
+
+        # The guard comes first, and reads `result` before anything is asked of
+        # it. It used to run second: the body was parsed on the line above,
+        # so `result.nil?` could never be reached -- a nil result raised
+        # `NoMethodError` on nil instead of taking the branch written for it.
+        # Fixing the missing constant alone would have exposed exactly that,
+        # which is why both were fixed in one pass.
+        return if result && result.status == 201
+
+        # `raise UnauthorizedError.refusal_from(...)`, raising an instance,
+        # rather than `raise UnauthorizedError, "message"`. The two-argument
+        # `raise Class, message` form calls `Class.exception(message)` and can
+        # pass nothing else, so it structurally could not carry intake's status
+        # however willing `UnauthorizedError` was to accept one -- which is how
+        # every refusal from this path was going to arrive as the class's 401
+        # default, including the 403 that means "your credential is fine, you
+        # have no grant for this endpoint".
+        raise UnauthorizedError.refusal_from(result, "Authentication")
       end
     end
   end
-end
+end

data/lib/end_point_blank/rails/authorized.rb

@@ -3,7 +3,7 @@ require "active_support/concern"
 module EndPointBlank
   module Rails
     module Authorized
-     extend ActiveSupport::Concern
+      extend ActiveSupport::Concern
 
       included do
         before_action :authorize!
@@ -12,7 +12,13 @@ module EndPointBlank
       def authorize!
         result = EndPointBlank::Commands::EndpointAuthorize.authorize(request)
         if result.nil? || result.status != 201
-          raise UnauthorizedError.new(authorize_error_message(result), result&.status || 503)
+          # Shared with `Authenticated#authenticate!`. This path has always
+          # carried intake's status and that one dropped it; two copies of one
+          # decision is how that happens, so there is now one copy. Nothing
+          # this path produces for any input has changed -- the message and the
+          # status are the same for a refusal, for a 5xx, and for an intake
+          # that did not answer.
+          raise UnauthorizedError.refusal_from(result, "Authorization")
         end
         result_json = JSON.parse(result.body)
         app_env_id = result_json['data'][0]['source_application_environment_id']
@@ -21,16 +27,6 @@ module EndPointBlank
         # turns it into Deprecation / Sunset headers on the way out.
         ::EndPointBlank::Rack::EnvStore.set_deprecation(result_json['deprecation'])
       end
-
-      private
-
-      def authorize_error_message(result)
-        return "Authorization service unavailable" if result.nil?
-
-        parsed = JSON.parse(result.body) rescue nil
-        detail = parsed.is_a?(Hash) ? parsed["error"] : nil
-        "Authorization failed: #{detail || result.body}"
-      end
     end
   end
-end
+end

data/lib/end_point_blank/target_url.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module EndPointBlank
+  # The form of a caller's target URL that the SDK is allowed to use:
+  # scheme, host, port and path, nothing else (sc-1469).
+  #
+  # The caller controls the URL, and its userinfo, query or fragment can
+  # carry a secret. None of them is needed -- intake resolves the environment
+  # from scheme, host, port and path alone, and its BaseUrl.normalize refuses
+  # a URL carrying any of them (an empty `?` or `#` included), so sending them
+  # would leak them to intake AND guarantee the mint fails. So every URL is
+  # stripped here on the way in, and only the stripped form is sent to
+  # intake, used as a cache or failure key, logged, or kept on an error.
+  #
+  # Built from the parsed parts, never by splitting the string, so an empty
+  # `?` or `#` cannot slip through.
+  #
+  # Only http and https are accepted, because only they can name a provider.
+  # Any other scheme is refused rather than rebuilt: Ruby parses it with a
+  # scheme-specific class whose parts need not fit "scheme://host/path"
+  # (URI::FTP's path has no leading slash, so "ftp://h:21/x" would come out
+  # as "ftp://hx").
+  module TargetUrl
+    HTTP_SCHEMES = %w[http https].freeze
+    # intake's BaseUrl refuses any other port, so asking would only cost a
+    # request and a recorded failure.
+    VALID_PORTS = (1..65_535).freeze
+    private_constant :HTTP_SCHEMES, :VALID_PORTS
+
+    # @param url [String, nil] the URL a caller is about to call
+    # @return [String, nil] "scheme://host[:port]/path" (scheme and host
+    #   lowercased as intake's BaseUrl does, IPv6 in brackets, the port only
+    #   when it is not the scheme default, the path as given), or nil when url
+    #   cannot be parsed, is not http or https, has no host, or has a port
+    #   outside 1..65535 -- the caller must then refuse it without making any
+    #   request.
+    def self.strip(url)
+      return nil if url.nil?
+
+      uri = URI.parse(url.to_s)
+      return nil unless acceptable?(uri)
+
+      port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+      "#{uri.scheme}://#{uri.host.downcase}#{port}#{uri.path}"
+    rescue URI::Error
+      nil
+    end
+
+    # URI lowercases the scheme, so "HTTPS://..." is accepted here too.
+    def self.acceptable?(uri)
+      HTTP_SCHEMES.include?(uri.scheme) && !uri.host.to_s.empty? && VALID_PORTS.cover?(uri.port)
+    end
+    private_class_method :acceptable?
+  end
+end