end_point_blank 0.6.0 → 0.12.0

data/lib/end_point_blank/commands/authentication_cache.rb

@@ -1,12 +1,63 @@
 # frozen_string_literal: true
 
-require 'singleton'
+require "singleton"
 
 module EndPointBlank
   module Commands
     # Thread-safe singleton cache for storing authentication credentials.
-    # Capped at MAX_SIZE entries. When full, expired entries are evicted first;
-    # if still at capacity the entry expiring soonest is removed.
+    # It is scoped to a single Ruby process: there is nothing behind it but
+    # a plain Hash (no Rails.cache, Redis, or other shared store), so a
+    # Puma or Unicorn worker, and every separate app instance, each hold
+    # their own cache and their own view of cache_ttl. Nothing described
+    # below crosses a process boundary.
+    #
+    # Capped at MAX_SIZE entries. When full, stale entries are evicted first;
+    # if still at capacity, whichever remaining entry's recorded expires_at
+    # is earliest is removed (see the note on make_room_for below -- that is
+    # a heuristic, not exactly "closest to becoming stale").
+    #
+    # Validity is re-derived on every read against the cache_ttl configured
+    # AT READ TIME (sc-755), not just against the expiry computed when the
+    # entry was written:
+    #
+    #   - If cache_ttl is currently 0 (disabled), the ENTIRE cache **in
+    #     this process** is cleared -- every entry, not just the one looked
+    #     up or being stored -- on both a read and a store that observe the
+    #     disabled state. (Amended 2026-09-14: an earlier version of this
+    #     cache deleted only the single key being read, which let a
+    #     *different* key go on answering after cache_ttl was raised again
+    #     -- a revoked grant could resurrect. This matches the Elixir SDK's
+    #     sc-660 `AuthCache.clear/0`, which clears the whole ETS table on
+    #     the disabled get/put path.)
+    #     Because each process's cache is independent, this does not reach
+    #     any other worker or instance: each one clears only when it has
+    #     itself observed cache_ttl disabled and then handled an Authorized
+    #     request (or a direct cache call) while disabled. A worker sitting
+    #     idle, or one that has not yet picked up the new config, keeps
+    #     serving whatever it already cached until it does -- nothing here
+    #     coordinates that across processes, and there is no fleet-wide
+    #     schedule for when, or whether, any given process's turn comes.
+    #     Known residual, left unaddressed here rather than fixed: a disable
+    #     followed by a re-enable with **no cache read or store in between**
+    #     flushes nothing, because nothing ever observed the disabled state
+    #     to trigger the clear. This story does not add configure-time
+    #     flushing.
+    #   - Otherwise an entry HITs only while it is within BOTH its original
+    #     write-time expiry (so raising cache_ttl later never extends an
+    #     entry's life) AND the CURRENT cache_ttl measured from its write
+    #     time (so lowering cache_ttl shortens already-cached entries on
+    #     their next read, without waiting for the original expiry).
+    #
+    # This is deliberately not "remaining time until the original expiry <=
+    # the new ttl" -- that arithmetic drifts back into looking valid once
+    # enough real time has passed, even though the entry is older than the
+    # new ttl allows. Elapsed-since-write is compared to the current ttl
+    # directly instead.
+    #
+    # cache_ttl is always a non-negative Integer by the time this cache reads
+    # it: Configuration#cache_ttl= refuses nil, negative numbers and
+    # non-Integers at configure time (sc-970), so there is no invalid value
+    # left for this class to detect at read or store time.
     class AuthenticationCache
       include Singleton
 
@@ -23,16 +74,17 @@ module EndPointBlank
       # @return [Object] The stored credentials
       def store(key, credentials)
         return unless credentials
+
         @mutex.synchronize do
+          ttl = current_ttl
+          # A store made while disabled clears whatever is already cached,
+          # same as a disabled read -- see the class comment -- and inserts
+          # nothing itself.
+          next if clear_if_disabled!(ttl)
+
           now = Time.now
-          # Evict expired entries first
-          @cache.delete_if { |_, v| v[:expired_at] <= now }
-          # Evict the entry expiring soonest if still at capacity
-          if @cache.size >= MAX_SIZE
-            oldest_key = @cache.min_by { |_, v| v[:expired_at] }.first
-            @cache.delete(oldest_key)
-          end
-          @cache[key] = { expired_at: now + ::EndPointBlank::Configuration.instance.cache_ttl, credentials: credentials }
+          make_room_for(now, ttl)
+          @cache[key] = { written_at: now, expires_at: now + ttl, credentials: credentials }
         end
       end
 
@@ -41,11 +93,8 @@ module EndPointBlank
       # @return [Object, nil] The stored credentials or nil if not found
       def retrieve(key)
         @mutex.synchronize do
-          if @cache.key?(key)
-            @cache[key][:credentials] if @cache[key][:expired_at] > Time.now
-          else
-            nil
-          end
+          entry = valid_entry(key)
+          entry && entry[:credentials]
         end
       end
 
@@ -53,9 +102,7 @@ module EndPointBlank
       # @param key [String, Symbol] The identifier to check
       # @return [Boolean] True if credentials exist, false otherwise
       def exists?(key)
-        @mutex.synchronize do
-          @cache.key?(key) && @cache[key][:expired_at] > Time.now
-        end
+        @mutex.synchronize { !valid_entry(key).nil? }
       end
 
       # Remove credentials from the cache
@@ -90,6 +137,81 @@ module EndPointBlank
           @cache.size
         end
       end
+
+      private
+
+      # Looks up `key` against the CURRENT cache_ttl.
+      #
+      # If the cache is disabled, the entire cache is cleared -- see the
+      # class comment -- and this returns nil regardless of whether `key`
+      # was ever present (a disabled read of a key that was never cached
+      # still has to flush everything else).
+      #
+      # Otherwise, if `key` is present but stale under the current ttl, only
+      # that single entry is deleted. Must be called with @mutex already
+      # held: every delete here runs in the same critical section as the
+      # read that decided it was stale, so a concurrently-written fresh
+      # entry for the same key can never be the one removed.
+      def valid_entry(key)
+        ttl = current_ttl
+        return nil if clear_if_disabled!(ttl)
+
+        entry = @cache[key]
+        return nil unless entry
+
+        if fresh?(entry, Time.now, ttl)
+          entry
+        else
+          @cache.delete(key)
+          nil
+        end
+      end
+
+      # Already validated by Configuration#cache_ttl= -- see the class
+      # comment.
+      def current_ttl
+        ::EndPointBlank::Configuration.instance.cache_ttl
+      end
+
+      def cache_disabled?(ttl)
+        ttl <= 0
+      end
+
+      # If `ttl` means disabled, clears the whole cache and returns true;
+      # otherwise returns false and leaves the cache untouched. Shared by
+      # the read and write paths so "disabled" clears everything identically
+      # from either one -- see the class comment.
+      def clear_if_disabled!(ttl)
+        return false unless cache_disabled?(ttl)
+
+        @cache.clear
+        true
+      end
+
+      # Evict stale entries first (using the ttl we are about to write with
+      # -- the same rule a subsequent read would apply); if still at
+      # capacity, evict whichever remaining entry's recorded expires_at is
+      # earliest. That is a heuristic, not the true "closest to becoming
+      # stale under the current ttl" (which would be
+      # min(expires_at, written_at + ttl)) -- harmless today since it only
+      # ever picks among entries `fresh?` already accepted, but not the same
+      # claim as "expires soonest".
+      def make_room_for(now, ttl)
+        @cache.delete_if { |_, v| !fresh?(v, now, ttl) }
+        return if @cache.size < MAX_SIZE
+
+        oldest_key = @cache.min_by { |_, v| v[:expires_at] }.first
+        @cache.delete(oldest_key)
+      end
+
+      # An entry is fresh only while it is within BOTH its own write-time
+      # expiry (raising ttl later never extends it) AND the currently
+      # configured ttl measured from when it was written (lowering ttl
+      # shortens it immediately). Never compare remaining-time-to-expiry
+      # against the new ttl -- see the class comment.
+      def fresh?(entry, now, ttl)
+        now < entry[:expires_at] && (now - entry[:written_at]) < ttl
+      end
     end
   end
 end

data/lib/end_point_blank/commands/basic_authenticate.rb

@@ -1,5 +1,6 @@
 #!/bin/ruby
 
+require 'json'
 require_relative 'http'
 
 module EndPointBlank
@@ -12,23 +13,86 @@ module EndPointBlank
 
         def authenticate(request)
           client_auth = request.headers['Authorization']
-          auth = "Basic #{AuthorizationGenerate.generate}"
+          # `Authorization.intake_header` (the no-argument `Authorization.header`
+          # before sc-1469), as EndpointAuthorize uses. It previously read
+          # `"Basic #{AuthorizationGenerate.generate}"` -- a second constant
+          # this gem has never defined, so the only caller of this command
+          # could not have reached the network even once the caller's own
+          # missing constant was fixed. Fixing one without the other just moves
+          # the NameError a frame deeper.
+          #
+          # This already returns a complete "Basic <base64>" string; wrapping
+          # it in another "Basic " would send `Basic Basic ...` and intake
+          # would refuse every request. Basic is right here: this call goes to
+          # this service's own intake, never to a provider.
+          auth = Authorization.intake_header
           body = {
             path: request.route_uri_pattern.to_s.gsub(/\([^)]*\)/, ''),
             http_method: request.request_method,
             client_auth: client_auth,
             application: Configuration.instance.app_name,
             endpoint_version: VersionFinder.new.find(request),
-            ip_address: request.remote_ip
+            # `source_ip`, which is the key intake reads. This sent
+            # `ip_address` from the beginning -- and js, py and java copied it
+            # faithfully, so all four were wrong together until sc-320 fixed
+            # the three ports. intake ignores keys it does not cast, so nothing
+            # ever failed: `source_ip_address` was simply NULL on every
+            # authenticate row from a Rails application, and every per-source-IP
+            # question about authenticate traffic read as though there were
+            # none. EndpointAuthorize on the next path over has always sent it
+            # under the right name.
+            source_ip: request.remote_ip
           }
           response = Http.post(configuration.authorize_url, auth, body)
           return nil if response.nil?
           EndPointBlank.logger.info "Authentication response: #{response.status} - #{response.body}"
+          if response.status == 201
+            source_env_id = source_application_environment_id(response.body)
+            ::EndPointBlank::Rack::EnvStore.set_source_application_environment_id(source_env_id)
+          end
           if response.status > 299
             EndPointBlank.logger.error "Failed to authenticate: #{response.status} - #{response.body}"
           end
           response
         end
+
+        private
+
+        def source_application_environment_id(body)
+          parsed = JSON.parse(body)
+          # `JSON.parse` succeeds on any RFC 7159 document, not just objects --
+          # `null`, `[]`, `5` and `"x"` all parse cleanly. `.dig('data', 0, ...)`
+          # on any of those raises `TypeError`/`NoMethodError`, which nothing
+          # downstream rescues: it would escape `authenticate` and turn a 201
+          # intake just granted into a 500 for the caller. Guard the shape
+          # before reading fields out of it, the same way
+          # `UnauthorizedError.reason_from` guards its own parsed body.
+          unless parsed.is_a?(Hash)
+            EndPointBlank.logger.error(
+              "Authenticated, but the authorize response body was not a JSON " \
+              "object, so this request's responses, logs and errors will not " \
+              "name their caller: body=#{body}"
+            )
+            return nil
+          end
+
+          id = parsed.dig('data', 0, 'source_application_environment_id')
+          return id if id.is_a?(String) && !id.empty?
+
+          EndPointBlank.logger.error(
+            "Authenticated, but the authorize response has no " \
+            "data[0].source_application_environment_id, so this request's responses, " \
+            "logs and errors will not name their caller: body=#{body}"
+          )
+          nil
+        rescue JSON::ParserError => error
+          EndPointBlank.logger.error(
+            "Authenticated, but the authorize response body was not valid " \
+            "JSON, so this request's responses, logs and errors will not " \
+            "name their caller: #{error.message}"
+          )
+          nil
+        end
       end
 
       def self.included(base)

data/lib/end_point_blank/commands/bearer_generate.rb

@@ -2,6 +2,14 @@
 
 module EndPointBlank
   module Commands
+    BEARER_GENERATE_DEPRECATION =
+      "EndPointBlank::Commands::BearerGenerate is deprecated and will be removed: its header " \
+      "carries this service's own client_id/client_secret and is only valid for this service's " \
+      "own EndPointBlank intake. Never send it to a provider; use " \
+      "EndPointBlank::Authorization.header(base_url) for outbound calls (sc-1469).".freeze
+    BEARER_GENERATE_DEPRECATION_MUTEX = Mutex.new
+    private_constant :BEARER_GENERATE_DEPRECATION_MUTEX
+
     module BearerGenerateMethods
       module ClassMethods
         def configuration
@@ -9,12 +17,36 @@ module EndPointBlank
         end
 
         def generate()
+          warn_deprecated
           Base64.encode64(configuration.client_id + ":" + configuration.client_secret).gsub("\n", "")
         end
 
         def auth_header
           "Basic " + generate
         end
+
+        private
+
+        # Once per process, not once per call: this sits on a request path,
+        # and a warning per request would bury the log it is meant to reach.
+        # The first caller wins the flag under a mutex so two threads racing
+        # the first call still print one line.
+        #
+        # Kernel#warn with category: :deprecated is printed only while
+        # Warning[:deprecated] is on (`ruby -W:deprecated`, or
+        # `Warning[:deprecated] = true`), which is how Ruby gates its own
+        # deprecations; the gem has no ActiveSupport outside Rails to lean on.
+        def warn_deprecated
+          return if @deprecation_warned
+
+          BEARER_GENERATE_DEPRECATION_MUTEX.synchronize do
+            return if @deprecation_warned
+
+            @deprecation_warned = true
+          end
+
+          warn(BEARER_GENERATE_DEPRECATION, category: :deprecated)
+        end
       end
 
       def self.included(base)
@@ -26,6 +58,10 @@ module EndPointBlank
     # Creates a Base64-encoded string from the client_id and client_secret
     # configured in EndPointBlank::Configuration.
     # Use auth_header class method to get a properly formatted "Basic {credentials}" header.
+    #
+    # @deprecated The header carries this service's own client secret and is only valid
+    #   for this service's own EndPointBlank intake (see Authorization.intake_header).
+    #   Never send it to a provider; use Authorization.header(base_url) (sc-1469).
     class BearerGenerate
       include BearerGenerateMethods
     end

data/lib/end_point_blank/commands/endpoint_authorize.rb

@@ -40,6 +40,7 @@ module EndPointBlank
           # headers would appear only on cache misses, which reads as a flaky
           # feature rather than a missing one.
           if (cached = cache.retrieve(cache_key))
+            record_source_application_environment_id(cached)
             return CachedResponse.new(201, cached)
           end
 
@@ -64,17 +65,61 @@ module EndPointBlank
           # token, so the 401 retry that used to live here is gone: a 401 now
           # means the credential is wrong, which is worth surfacing rather
           # than retrying.
-          response = Http.post(configuration.authorize_url, Authorization.header, body)
+          response = Http.post(configuration.authorize_url, Authorization.intake_header, body)
 
           return nil if response.nil?
           EndPointBlank.logger.info "Authentication response: #{response.status} - #{response.body}"
           if response.status == 201
+            record_source_application_environment_id(response.body)
             cache.store(cache_key, response.body)
           elsif response.status > 299
             EndPointBlank.logger.error "Failed to authorize endpoint: #{response.status} - #{response.body}"
           end
           response
         end
+
+        private
+
+        # Intake renders the grant under data[0]. The Rails controller also
+        # records this value, but the command is also used directly (today,
+        # by end_point_blank_deploy's conformance driver), so the command must
+        # carry the grant into the request store before any writer runs.
+        def record_source_application_environment_id(body)
+          parsed = JSON.parse(body)
+          # A 201 whose body is valid JSON but not a Hash -- `[]`, `null`,
+          # `"x"` -- used to reach `dig` below and raise (TypeError for an
+          # Array, NoMethodError for nil or a String), turning a request
+          # intake had actually GRANTED into a crash for this direct-caller
+          # path. The other SDKs all guard the type before digging into the
+          # body (py: isinstance on both levels, js: optional chaining,
+          # elixir: pattern match with a fallback clause); this matches them.
+          unless parsed.is_a?(Hash)
+            EndPointBlank.logger.error(
+              "Authorized, but the response body did not parse to a JSON object, so this " \
+              "request's responses, logs and errors will not name their caller: body=#{body}"
+            )
+            return ::EndPointBlank::Rack::EnvStore.set_source_application_environment_id(nil)
+          end
+
+          id = parsed.dig('data', 0, 'source_application_environment_id')
+          # An empty string is the same absence as a missing id -- do not
+          # record it, or the log line above claiming the caller "will not be
+          # named" is contradicted by the very next line.
+          id = nil if id == ''
+          if id.nil?
+            EndPointBlank.logger.error(
+              "Authorized, but the response has no data[0].source_application_environment_id, " \
+              "so this request's responses, logs and errors will not name their caller: body=#{body}"
+            )
+          end
+          ::EndPointBlank::Rack::EnvStore.set_source_application_environment_id(id)
+        rescue JSON::ParserError
+          EndPointBlank.logger.error(
+            "Authorized, but the response body is not valid JSON, so this request's responses, " \
+            "logs and errors will not name their caller: body=#{body}"
+          )
+          ::EndPointBlank::Rack::EnvStore.set_source_application_environment_id(nil)
+        end
       end
 
       def self.included(base)

data/lib/end_point_blank/commands/endpoint_update.rb

@@ -19,7 +19,7 @@ module EndPointBlank
       end
 
       def auth
-        Authorization.header
+        Authorization.intake_header
       end
 
       def write(data)
@@ -28,7 +28,7 @@ module EndPointBlank
           "app_version=#{data[:app_version]}"
 
         response = Excon.post(configuration.endpoint_update_url,
-          headers: {'Authorization' => auth, 'Content-Type' => 'application/json'},
+          headers: EndPointBlank::Commands::Http.headers(auth),
           body: data.to_json,
           **EndPointBlank::Commands::Http::TIMEOUT_OPTIONS
         )