end_point_blank 0.6.1 → 0.13.0

data/lib/end_point_blank/management/transport.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "excon"
+require "json"
+require "uri"
+require_relative "../version"
+require_relative "error"
+require_relative "retry_policy"
+require_relative "idempotency_key"
+require_relative "url_path"
+
+module EndPointBlank
+  module Management
+    # The HTTP layer under {Client}: one request to the management API, with
+    # its headers, its Idempotency-Key and its retries. Built on Excon, the
+    # HTTP library the rest of this gem already uses.
+    #
+    # Retries (at most +max_retries+ after the first attempt, each wait passed
+    # to +sleeper+):
+    #
+    # - 429 +rate_limited+, any method: after Retry-After seconds. Nothing was
+    #   done, so even a PATCH is safe to send again. A Retry-After longer than
+    #   +max_retry_wait+ is not waited out; the error is raised instead.
+    # - 409 +idempotency_request_in_progress+ (POST only): shortly, with the
+    #   same key, so the first request's answer is replayed once it finishes.
+    # - 5xx (+internal_server_error+, +audit_unavailable+,
+    #   +intake_unavailable+, or a proxy's 502/503/504) and requests that never
+    #   got an answer: for GET and DELETE, which are idempotent, and for POST,
+    #   which always carries an Idempotency-Key. Never for PATCH.
+    #
+    # Every POST carries an Idempotency-Key (a random UUID v4 unless the
+    # caller passed one), and every retry of it sends the same key.
+    #
+    # 409 +idempotency_replay_unavailable+ is never retried: the first POST
+    # succeeded and its answer held a secret shown only once.
+    class Transport
+      API_PREFIX = "/api/v1"
+
+      attr_reader :base_url
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(api_key:, base_url:, max_retries:, max_retry_wait:, connect_timeout:, read_timeout:,
+                     sleeper:, excon_options: {})
+        @api_key = api_key
+        @base_url = base_url
+        @base_path = UrlPath.strip_trailing_slashes(URI.parse(base_url).path)
+        @retry_policy = RetryPolicy.new(max_retries: max_retries, max_retry_wait: max_retry_wait)
+        @connect_timeout = connect_timeout
+        @read_timeout = read_timeout
+        @sleeper = sleeper
+        @excon_options = excon_options
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Sends one API request and answers its decoded JSON body (nil for an
+      # empty body). +path+ is under /api/v1, e.g. "/organization".
+      #
+      # @raise [Error] for any answer outside 2xx, once retries are spent
+      def request(method, path, query: nil, body: nil, idempotency_key: nil)
+        method = method.to_s.upcase
+        idempotency_key = IdempotencyKey.resolve(method, idempotency_key)
+        attempt = 0
+
+        loop do
+          result = attempt_request(method, path, query, body, idempotency_key)
+          return result unless result.is_a?(Error)
+
+          wait_before_retry(method, path, result, attempt)
+          attempt += 1
+        end
+      end
+
+      def self.user_agent
+        "end_point_blank-ruby/#{EndPointBlank::VERSION} (management)"
+      end
+
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect}>"
+      end
+
+      private
+
+      # The decoded body on success, or the Error to raise or retry on.
+      def attempt_request(method, path, query, body, idempotency_key)
+        response = perform(method, path, query, body, idempotency_key)
+        return Error.from_response(**error_fields(response, method, path)) unless success?(response)
+
+        decode(response, method, path)
+      rescue Excon::Error::StubNotFound
+        raise
+      rescue Excon::Error => e
+        connection_error(e, method, path)
+      end
+
+      def perform(method, path, query, body, idempotency_key)
+        connection = Excon.new(base_url, connect_timeout: @connect_timeout, read_timeout: @read_timeout,
+                                         write_timeout: @read_timeout, persistent: false, **@excon_options)
+        params = { method: method, path: "#{@base_path}#{API_PREFIX}#{path}",
+                   headers: headers(body, idempotency_key) }
+        params[:query] = query if query && !query.empty?
+        params[:body] = JSON.generate(body) unless body.nil?
+        connection.request(params)
+      end
+
+      def headers(body, idempotency_key)
+        headers = {
+          "Authorization" => "Bearer #{@api_key}",
+          "Accept" => "application/json",
+          "User-Agent" => self.class.user_agent
+        }
+        headers["Content-Type"] = "application/json" unless body.nil?
+        headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        headers
+      end
+
+      def success?(response)
+        (200..299).cover?(response.status)
+      end
+
+      def decode(response, method, path)
+        text = response.body.to_s
+        return nil if text.strip.empty?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        Error.new("The management API answered HTTP #{response.status} with a body that is not JSON.",
+                  code: ErrorCodes::INVALID_RESPONSE, status: response.status, http_method: method, path: path)
+      end
+
+      def error_fields(response, method, path)
+        { status: response.status, headers: response.headers, body: response.body,
+          http_method: method, path: path }
+      end
+
+      def connection_error(error, method, path)
+        detail = redact("#{error.class.name}: #{error.message}")
+        Error.new("Could not reach the management API at #{base_url} (#{detail}).",
+                  code: ErrorCodes::CONNECTION_ERROR, http_method: method, path: path)
+      end
+
+      # Sleeps before the next attempt, or raises +error+ when it is not to
+      # be retried.
+      def wait_before_retry(method, path, error, attempt)
+        delay = @retry_policy.delay(method, error, attempt)
+        raise error if delay.nil?
+
+        log_retry(method, path, error, delay)
+        @sleeper.call(delay)
+      end
+
+      # Method, path, status and code only: never headers, query or bodies,
+      # which carry the key, ids and credential secrets.
+      def log_retry(method, path, error, delay)
+        EndPointBlank.logger.debug(
+          "[EndPointBlank] management API #{method} #{path} answered " \
+          "#{error.status || "no response"} (#{error.code}); retrying in #{delay}s"
+        )
+      end
+
+      def redact(text)
+        return text if @api_key.nil? || @api_key.empty?
+
+        text.gsub(@api_key, "[REDACTED]")
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/url_path.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # URL string helpers for the management client.
+    module UrlPath
+      SLASH = "/".ord
+
+      # +text+ without trailing slashes. One backward scan over the bytes, not
+      # a regex, so its cost is linear however the input is shaped.
+      def self.strip_trailing_slashes(text)
+        stop = text.bytesize
+        stop -= 1 while stop.positive? && text.getbyte(stop - 1) == SLASH
+        text.byteslice(0, stop)
+      end
+    end
+  end
+end

data/lib/end_point_blank/management.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "configuration_error"
+require_relative "management/configuration"
+require_relative "management/error_codes"
+require_relative "management/error"
+require_relative "management/page"
+require_relative "management/retry_policy"
+require_relative "management/idempotency_key"
+require_relative "management/url_path"
+require_relative "management/transport"
+require_relative "management/client"
+
+module EndPointBlank
+  # The organization management API client. See {Management::Client}.
+  #
+  # Configure defaults once, e.g. in config/initializers/end_point_blank.rb,
+  # apart from the runtime's EndPointBlank.configure:
+  #
+  #   EndPointBlank::Management.configure do |m|
+  #     m.api_key = Rails.application.credentials.dig(:end_point_blank, :management_key)
+  #   end
+  #
+  #   EndPointBlank::Management.client.organization
+  module Management
+    @configuration_mutex = Mutex.new
+
+    class << self
+      # The defaults {Client.new} reads. @return [Configuration]
+      def configuration
+        @configuration_mutex.synchronize { @configuration ||= Configuration.new }
+      end
+
+      # Yields {configuration} to change the defaults.
+      def configure
+        yield configuration
+        configuration
+      end
+
+      # A new {Client} from {configuration}; +options+ override it.
+      # @return [Client]
+      def client(**options)
+        Client.new(**options)
+      end
+
+      # Back to the built-in defaults (for tests).
+      def reset_configuration!
+        @configuration_mutex.synchronize { @configuration = Configuration.new }
+      end
+    end
+  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

data/lib/end_point_blank/token_unavailable_error.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "target_url"
+
+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 by {Authorization.header} when no access token can be obtained for
+  # an outbound call to a provider.
+  #
+  # There is deliberately no fallback. Before sc-1469 a failed mint silently
+  # produced "Basic base64(client_id:client_secret)" instead, which sent this
+  # service's own credential to whichever provider it was calling (and to
+  # that provider's intake). A client must never do that, so the call cannot
+  # be authorized and the caller has to decide what to do: retry, degrade, or
+  # fail its own request.
+  #
+  # `base_url` is the URL the token was wanted for with its userinfo, query
+  # and fragment removed ({TargetUrl.strip}), or nil when it could not be
+  # parsed. The raw value is never kept: the caller already has it, and a
+  # field on an exception reaches error reporting as surely as the message
+  # does.
+  #
+  # `failure` is the {AccessTokens::Failure} recorded for the mint, when one
+  # was recorded, so a handler can branch on `failure.outcome`
+  # (:credential_rejected, :request_rejected, :server_error,
+  # :transport_error) exactly as it would after calling
+  # {AccessTokens.last_failure} itself.
+  #
+  # A mint that raised is constructed with `unexpected: true` and reported as
+  # :transport_error, with the exception as `cause` (Ruby sets it when this
+  # is raised from the rescue). Its message is deliberately not copied into
+  # this one.
+  class TokenUnavailableError < Error
+    attr_reader :base_url, :failure
+
+    # @param base_url [String] the URL the token was wanted for
+    # @param failure [AccessTokens::Failure, nil] why the mint failed
+    # @param unexpected [Boolean] true when the mint raised rather than
+    #   reporting a failure
+    def initialize(base_url, failure = nil, unexpected: false)
+      @base_url = TargetUrl.strip(base_url)
+      @failure = failure
+      @unexpected = unexpected
+      super(build_message)
+    end
+
+    # @return [Boolean] true when the mint raised; `cause` holds what it raised
+    def unexpected?
+      @unexpected
+    end
+
+    # @return [Symbol, nil] the failure outcome, or nil when none was recorded
+    def outcome
+      failure&.outcome
+    end
+
+    # @return [Integer, nil] intake's HTTP status, or nil when it never answered
+    def status
+      failure&.status
+    end
+
+    private
+
+    UNPARSEABLE_URL = "the requested URL (not shown: it could not be parsed)"
+    private_constant :UNPARSEABLE_URL
+
+    # One fixed text per outcome, the same in every EndPointBlank SDK. Never
+    # intake's response body (Failure#reason) or an exception message: the
+    # message is what reaches logs and error reporting, and neither is ours
+    # to vouch for. Failure#reason stays available on #failure.
+    def reason # rubocop:disable Metrics/MethodLength
+      # Before the outcome, because a mint that raised is also :transport_error.
+      return "the token request failed unexpectedly" if unexpected?
+
+      http = status ? " (HTTP #{status})" : ""
+
+      case outcome
+      when :credential_rejected
+        "intake rejected this application's client credential#{http}; " \
+          "retrying cannot help -- re-issue the credential"
+      when :request_rejected
+        "intake refused the token request#{http}; check the URL and that a grant covers the target"
+      when :server_error
+        "intake failed to issue a token#{http}; this may be transient"
+      when :transport_error
+        "intake could not be reached (timeout, connection refused or retries exhausted); " \
+          "this may be transient"
+      else
+        "the token request failed for an unknown reason"
+      end
+    end
+
+    def build_message
+      "Could not mint an EndPointBlank access token for #{base_url || UNPARSEABLE_URL}: #{reason}. " \
+        "EndPointBlank never sends this service's client_id/client_secret to a provider, " \
+        "so there is no Basic-auth fallback and the call must not be made without a token."
+    end
+  end
+end

data/lib/end_point_blank/unauthorized_error.rb

@@ -1,4 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
 module EndPointBlank
+  # Raised when a request fails authentication or authorization.
+  #
+  # This error is intentionally not logged by the middleware, as unauthorized
+  # access attempts are expected to occur.
+  #
+  # `status` carries the status intake answered the authenticate or authorize
+  # call with, so a handler can tell the two refusals apart: 401 means the
+  # credential was not accepted and the integrator should check it, 403 means
+  # the credential was fine but no grant covers this endpoint and the
+  # integrator should ask for one. Collapsing both to 401 sends them to debug
+  # the wrong thing. The other SDKs each carry the same value under their own
+  # idiomatic name -- `statusCode` in JS, `getStatusCode()` in Java,
+  # `status_code` in Python; this is Ruby's.
+  #
+  # It defaults to 401 so that `UnauthorizedError.new(message)` keeps working
+  # unchanged, and because 401 is the safe reading of a refusal that arrives
+  # with no status attached. The concerns never lean on that default: they pass
+  # intake's status, or 503 when intake did not answer at all.
   class UnauthorizedError < StandardError
     attr_reader :status
 
@@ -6,5 +28,63 @@ module EndPointBlank
       super(message)
       @status = status
     end
+
+    # Builds the error for a non-201 answer to intake's authenticate or
+    # authorize call. `action` is "Authentication" or "Authorization".
+    #
+    # One method rather than a copy per concern. `Rails::Authenticated` and
+    # `Rails::Authorized` were two transcriptions of one decision, and two
+    # copies is how one path acquires a fix the other does not. That is not
+    # hypothetical here: `authorize!` passed intake's status and read the body
+    # defensively, while `authenticate!` used `raise UnauthorizedError,
+    # "message"` -- the two-argument `raise Class, message` form, which
+    # structurally cannot pass a status however willing this class is to accept
+    # one -- and parsed the body before it had checked there was a body to
+    # parse. Both are fixed here, once.
+    #
+    # @param result [#status, #body, nil] intake's answer, or nil if it did not
+    #   answer at all.
+    # @param action [String] the word naming what was attempted.
+    # @return [UnauthorizedError]
+    def self.refusal_from(result, action)
+      if result.nil?
+        # Intake never answered at all, so nothing refused this caller and 401
+        # would blame a credential that was never judged. 503 says the true
+        # thing -- the check could not be made -- and is what the other four
+        # SDKs already send for this same case: JS and Java
+        # `response ? response.status : 503`, Python's `refusal_from`, and
+        # Elixir's literal `send_resp(503, ...)`. It is also the one case the
+        # "service unavailable" wording is actually true for.
+        #
+        # The wording deliberately has no "#{action} failed:" prefix, because
+        # that is what `authorize!` has always sent for this case and this
+        # method must not change what the working path produces for any input.
+        # The other SDKs prefix it; the status, which is what a handler
+        # branches on, agrees with them.
+        return new("#{action} service unavailable", 503)
+      end
+
+      # Intake's verdict verbatim. 401 tells an integrator to check the
+      # credential, 403 tells them to ask for a grant.
+      new("#{action} failed: #{reason_from(result)}", result.status)
+    end
+
+    # intake sends `{"error": "..."}`, but the SDK reaches it through a proxy
+    # and a WAF or load balancer can answer with an HTML page intake never
+    # generated. An unparseable body is therefore an expected case, not a
+    # swallowed failure: it falls back to the raw body so the operator still
+    # sees exactly what came back rather than an empty reason.
+    def self.reason_from(result)
+      parsed =
+        begin
+          JSON.parse(result.body)
+        rescue StandardError
+          nil
+        end
+
+      detail = parsed.is_a?(Hash) ? parsed["error"] : nil
+      detail || result.body
+    end
+    private_class_method :reason_from
   end
-end
+end

data/lib/end_point_blank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EndPointBlank
-  VERSION = "0.6.1"
+  VERSION = "0.13.0"
 end