end_point_blank 0.2.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b93be9173755a967ce4c1f1d38205b8803bc175ec1d029f860c6620807553bca
-  data.tar.gz: 74ff753691ea46be3ac391cea6b178673a8fb4cd7e0b6ea2861b9646d138e710
+  metadata.gz: edb9e7eb50879a3caf5cec7ae59210d29a3096e82d68c997dd4ae545cac00e2d
+  data.tar.gz: 4bd84f05bf328b387fdb6213194c4920c0282cb6eaaee0ad1eb20610785d53bb
 SHA512:
-  metadata.gz: 4533c807575899944c7626e716585018309a55311d659b0e2b3fa5005b0ab5b825bec2ef89a0b3d9108277ddac28cc985c75c6047ded18542c2d4dceeace66f1
-  data.tar.gz: d7a5148cba59e40aaf3190b8147800e4777882ff08c31e9245ede3f289eff1eedb2c43dfe034587bf52cf2b23518b2d6cdbe4435e90235c71418d433c1d9b16c
+  metadata.gz: b958fd1b769033e6fe4420e371b568ec449fb55accac06c7ebb82a2a1ac0b2415770117c4d61b9746af87ef8d27e97c7e0888dbb3bfc55cba605f10c5d57d91d
+  data.tar.gz: 3ef96dd88833a733d9f4dd30592618df157ef6af60483c50aad82e2306c60ffb78348c9a7256a52102d34647b148ab8d58109b25088cf6480cd075b054d46d72

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.6.0
+
+### Breaking
+
+- **`Authorization.header` and `AccessTokens.token` now take a URL, not a
+  hostname.** Pass the URL you are about to call —
+  `https://api.example.com/orders`, not `api.example.com`. Strip any query
+  string or fragment first; they are rejected. Earlier READMEs showed the
+  hostname form; those examples no longer work.
+- **`AccessTokens#exists?` now requires the same URL argument.** It answers
+  for the entry covering that URL; there is no longer a single process-wide
+  token for it to answer about.
+- **Requires an intake that accepts `base_url`.** An older intake returns
+  `400 {"error":"Missing required parameter: base_url"}`.
+
+### Changed
+
+- `endpoint_authorize` authenticates to intake with Basic instead of minting
+  an access token for itself. The inbound request path no longer touches the
+  token cache at all.
+- A 401 from the authorize endpoint is returned to the caller rather than
+  retried once. With Basic, a 401 means the credential is wrong.
+- Tokens are cached per application environment, keyed on the canonical base
+  URL intake resolves the request to, rather than one per process.
+
+### Security
+
+- The minted bearer token was previously written to the host application's
+  logs at info level: every successful token exchange logged the full intake
+  response body, which contains the live token, whenever your app's Rails
+  logger was set to info or more verbose. This release logs only the
+  response status code. If your logs go back further than this upgrade,
+  treat them as potentially containing live bearer tokens and handle them
+  per your own retention/rotation policy.

data/HARDENING_REPORT.md

@@ -0,0 +1,210 @@
+# Hardening report — end_point_blank (Rails/Ruby client lib) — P2 #14
+
+Branch: `harden-timeouts-bounded-queue` (off `master`, not pushed)
+
+## Goal
+
+Bring this lib's reliability posture in line with the Elixir sibling lib,
+which was hardened with per-attempt HTTP timeouts (connect 3s / read 5s)
+and a bounded, drop-oldest background send queue (cap 1000, throttled
+warning on drop).
+
+## Gap 1 — Excon calls with no timeout
+
+### Every `Excon.` call site in the lib (confirmed via `grep -rn "Excon\." lib/`)
+
+| File | Line | Call |
+|---|---|---|
+| `lib/end_point_blank/commands/http.rb` | 23 | `Excon.post` (shared fire-and-forget POST helper, used by `DirectWriter`) |
+| `lib/end_point_blank/commands/generate_access_token.rb` | 20 | `Excon.post` (access-token exchange) |
+| `lib/end_point_blank/commands/endpoint_update.rb` | 30 | `Excon.post` (endpoint/route registration) |
+
+All three are the only `Excon.*` calls in the lib. No other `Excon.new`/etc. exist.
+
+### Fix
+
+Added a single shared constant in `lib/end_point_blank/commands/http.rb`:
+
+```ruby
+CONNECT_TIMEOUT = 3
+READ_TIMEOUT    = 5
+TIMEOUT_OPTIONS = { connect_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT }.freeze
+```
+
+- `Http.post` now passes `**TIMEOUT_OPTIONS` directly.
+- `generate_access_token.rb` and `endpoint_update.rb` each `require_relative 'http'`
+  and splat `**EndPointBlank::Commands::Http::TIMEOUT_OPTIONS` into their own
+  `Excon.post` calls, so the values live in exactly one place.
+
+### Timeout error handling
+
+`Excon::Error::Timeout` is a subclass of `Excon::Error` (verified against the
+installed excon 1.5.0 source), so:
+
+- `Http.post`'s existing `rescue Excon::Error => e` already covers timeouts —
+  it retries up to `MAX_ATTEMPTS` (3) then logs and returns `nil`. No caller
+  ever sees an exception.
+- `generate_access_token.rb`'s existing `rescue => e` (StandardError) already
+  covered timeouts too.
+- `endpoint_update.rb` had a **latent bug**: `rescue Excon::Error::Socket,
+  Excon::Error::Connection => e`. `Excon::Error::Connection` **does not
+  exist** in excon 1.5.0 (only `Excon::Error::Socket`, `Excon::Error::Timeout`,
+  etc. are defined under `Excon::Error`). Because Ruby resolves rescue-clause
+  constants lazily, this clause would silently work until an exception was
+  actually raised inside the `begin` block, at which point evaluating
+  `Excon::Error::Connection` would raise `NameError` and crash the caller —
+  i.e. a network blip or a timeout during endpoint registration would have
+  thrown `NameError` instead of being handled gracefully. Fixed by rescuing
+  `Excon::Error` broadly (matching the pattern in `http.rb`), which now also
+  correctly covers `Excon::Error::Timeout`.
+
+### Incidental fix required to exercise the above in tests
+
+`lib/end_point_blank/authorization.rb` calls `Base64.encode64` for the Basic
+auth header path but never `require 'base64'`. On Ruby 3.4 `base64` was
+removed from default gems, so this raised `NameError` / `LoadError` the
+moment that code path executed (which is exactly the path exercised in the
+`endpoint_update` timeout test, since it needs an `Authorization.header` call
+with no cached token). Fixed by adding `require 'base64'` in
+`authorization.rb` and declaring `spec.add_dependency "base64"` in the
+gemspec (ran `bundle install`, updating `Gemfile.lock`). This was a real
+reliability bug independent of this task — any Basic-auth call path in this
+gem on Ruby >= 3.4 without `base64` explicitly in the app's own Gemfile would
+have crashed.
+
+## Gap 2 — unbounded background queue
+
+`lib/end_point_blank/writers/delayed_writer.rb` used a plain `Queue.new`
+(unbounded). During an intake outage, the 2 background drain threads block
+on failed/slow POSTs and the queue grows without bound → OOM risk.
+
+### Fix
+
+`Queue` has no `max` option, so the bound is implemented explicitly:
+
+- `MAX_QUEUE_SIZE = 1000`.
+- `enqueue` (public API, accepts a single payload or an array, unchanged
+  signature) now routes each item through `enqueue_one`, which is guarded by
+  a `Mutex` (`enqueue_mutex`) so the check-then-drop-then-push sequence is
+  atomic across concurrent producer threads (the request/response/log/error
+  writer call paths).
+- If `queue.size >= MAX_QUEUE_SIZE` when a new item arrives, the **oldest**
+  item is dropped first (`pop_additional`, a non-blocking `Queue#pop(true)`,
+  which removes from the front of the FIFO `Queue`), then the new item is
+  pushed. Net effect: queue never exceeds 1000, newest items win.
+- Drop warnings are throttled: `note_drop` tracks a drop counter and only
+  logs (via `log_warning`, which prefers `::Rails.logger.warn` and falls
+  back to `Kernel#warn` when Rails isn't loaded) at most once per
+  `WARN_THROTTLE_SECONDS` (30s), with the message including how many items
+  were dropped since the last warning — so a sustained outage doesn't itself
+  become a logging flood.
+- The existing 2-thread drain model (`start_threads`) is unchanged in
+  structure; internal `@queue` access was switched to a `queue` reader
+  (`@queue ||= Queue.new`) so both the drain threads and the new bounded
+  `enqueue_one` share the same lazily-initialized queue, and so tests can
+  instantiate a bare object that mixes in `DelayedWriter` and drive
+  `enqueue`/`queue` without needing to spin up the background threads.
+
+## Sinatra coverage
+
+Confirmed: `end_point_blank_sinatra/Gemfile` depends on
+`gem 'end_point_blank', path: '../end_point_blank_rails'` and
+`end_point_blank_sinatra/app.rb` does `require 'end_point_blank'`, which is
+this gem's single entry point (`lib/end_point_blank.rb`) that requires every
+file touched here (`commands/http`, `commands/generate_access_token`,
+`commands/endpoint_update`, `writers/delayed_writer`, `authorization`).
+There is no Sinatra-specific fork of any of this code. **Sinatra is
+covered.**
+
+## Tests added (TDD: written first, confirmed red against the pre-fix code, then made green)
+
+- `spec/commands_http_spec.rb` — asserts `Excon.post` is called with
+  `connect_timeout`/`read_timeout` matching the shared constants; asserts a
+  raised `Excon::Error::Timeout` is retried `MAX_ATTEMPTS` times, logged, and
+  returns `nil` without raising.
+- `spec/generate_access_token_spec.rb` — asserts the same timeout options
+  reach `Excon.post` for the access-token exchange; asserts a timeout
+  doesn't raise.
+- `spec/endpoint_update_spec.rb` — asserts the same timeout options reach
+  `Excon.post` for endpoint registration; asserts a timeout doesn't raise
+  and is logged via `Rails.logger.warn` (this is the test that caught both
+  the `Excon::Error::Connection` NameError bug and the missing
+  `require 'base64'`).
+- `spec/delayed_writer_spec.rb` — mixes `DelayedWriter` into a bare test
+  class (without starting background threads, so the queue can be inspected
+  synchronously): asserts the queue never exceeds `MAX_QUEUE_SIZE`, asserts
+  the oldest items are dropped first (FIFO order preserved for survivors),
+  asserts normal FIFO enqueue/dequeue when under the cap, asserts array-form
+  `enqueue` also respects the bound, and asserts `log_warning` is called
+  only **once** across 50 drops (throttling), not once per drop.
+
+All four spec files were confirmed to fail (9 of 11 new examples red) against
+the original code before implementing the fix, then confirmed green after.
+
+## Test evidence
+
+```
+$ bundle exec rspec
+...
+49 examples, 0 failures
+```
+
+Also ran the project's actual CI commands directly:
+
+```
+$ ./build.sh   # bundle install — passes
+$ ./test.sh    # bundle exec rspec — 49 examples, 0 failures
+```
+
+`bundle exec ruby -Ilib -e "require 'end_point_blank'"` loads cleanly and
+`EndPointBlank::Commands::Http::TIMEOUT_OPTIONS` /
+`EndPointBlank::Writers::DelayedWriter::MAX_QUEUE_SIZE` are inspectable at
+the top level, confirming the constants are reachable as documented.
+
+`rubocop` was also run for hygiene (not part of CI — `ci.yml` only runs
+`./test.sh`, i.e. rspec). It reports 46 offenses across the 5 touched files
+vs. 43 pre-existing on the same files before this change — the 3 new ones
+are `Metrics/AbcSize`/`Metrics/MethodLength` on `start_threads`, whose body
+is unchanged except swapping `@queue` for the new `queue` reader method; all
+newly-added methods (`enqueue_one`, `drop_oldest_and_note`, `note_drop`,
+`warn_dropped_items`, `log_warning`) were kept short enough to avoid adding
+further offenses. None of this blocks CI.
+
+## Files changed
+
+- `lib/end_point_blank/commands/http.rb` — shared timeout constants/helper,
+  applied to `Http.post`.
+- `lib/end_point_blank/commands/generate_access_token.rb` — applies shared
+  timeout options to its `Excon.post`.
+- `lib/end_point_blank/commands/endpoint_update.rb` — applies shared timeout
+  options to its `Excon.post`; fixed the broken `Excon::Error::Connection`
+  rescue clause to `rescue Excon::Error` (now also catches `Timeout`).
+- `lib/end_point_blank/writers/delayed_writer.rb` — bounded, drop-oldest,
+  throttled-warning queue.
+- `lib/end_point_blank/authorization.rb` — `require 'base64'` (incidental
+  fix, needed for the Basic-auth path to work at all on Ruby 3.4, and
+  required to exercise the `endpoint_update` timeout test end-to-end).
+- `end_point_blank.gemspec`, `Gemfile.lock` — declare `base64` as an
+  explicit dependency (Ruby 3.4 removed it from default gems).
+- New specs: `spec/commands_http_spec.rb`, `spec/generate_access_token_spec.rb`,
+  `spec/endpoint_update_spec.rb`, `spec/delayed_writer_spec.rb`.
+
+## Concerns / follow-ups (not fixed here, out of scope for P2 #14)
+
+- The queue bound is a soft/approximate guarantee under heavy concurrent
+  enqueue: the mutex only guards the *decision* to drop before push, so with
+  many producer threads racing, the queue could very briefly be examined by
+  more than one thread between the `pop`/`push` pair in rare interleavings
+  is prevented by the mutex — but a concurrent **drain** thread popping at
+  the same moment only ever shrinks the queue, never grows it past the cap.
+  In practice the bound holds exactly given the mutex around all enqueue-side
+  mutation.
+- `note_drop`/`@last_drop_warning_at` state lives on the writer singleton
+  instance (`RequestWriter`, `ResponseWriter`, `ExceptionWriter`,
+  `LogWriter` each get their own independent throttle window since they each
+  `include DelayedWriter` separately) — this is intentional (matches
+  per-queue behavior) but worth knowing if someone expects a single global
+  throttle across all four queues.
+- Rubocop was not run as part of CI before this change and still isn't;
+  pre-existing style debt (43 offenses) was left alone except where it was
+  directly in code I touched and cheap to avoid growing.

data/README.md

@@ -79,6 +79,7 @@ Every setting listed below can be set explicitly in that block, and most also fa
 | `worker_count` | — | `4` | Currently unused by the delayed writer (which always spins up 2 threads); reserved. |
 | `token_ttl` | — | `nil` | Optional TTL (seconds) requested when generating a `Bearer` access token. |
 | `cache_ttl` | — | `300` | TTL (seconds) for the authorization decision cache. |
+| `trust_proxy_headers` | — | `true` | Whether the per-request `scheme`/`host`/`port` report honors `X-Forwarded-Proto`/`-Host`/`-Port`. See [Reported base URL](#reported-base-url). |
 | `masking_rules` | — | `[]` | Ordered list of masking rule hashes — see [Data masking](#data-masking). |
 | `mask_hook` | — | `nil` | Optional `->(payload, record_type_string) { payload }` run after `masking_rules`. |
 | `version_finder` | — | `nil` | Optional `->(request) { "1" }` overriding `EndPointBlank::Commands::VersionFinder`'s default header/param/path detection. |
@@ -88,6 +89,35 @@ Note: there is also a bare `environment` accessor on `Configuration`, but it is
 code path in this gem (the real per-request environment name is `env_name`, described above) — do
 not rely on it.
 
+### Reported base URL
+
+Every request payload carries the base URL the *caller* used, as three separate fields —
+`scheme`, `host` and `port`. A field that cannot be resolved is omitted rather than sent as
+null. EndPointBlank uses these to fill in an application environment's base URL for you,
+instead of asking someone to type it.
+
+By default the gem honors `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-Port`,
+reading the **last** comma-separated hop. It does this on its own, without consulting Rails'
+or Rack's trusted-proxy configuration, so that all five EndPointBlank clients answer
+identically for the same request.
+
+**Turn this off if your application is reachable directly, with no proxy in front of it** —
+or if you would simply rather report nothing than report something a caller could influence:
+
+```ruby
+EndPointBlank.configure { |c| c.trust_proxy_headers = false }
+```
+
+With it off, the `X-Forwarded-*` headers are ignored entirely and `scheme`, `host` and `port`
+come from the connection and the `Host` header only.
+
+It defaults to `true` because the alternative is worse for almost everyone. Most production
+deployments sit behind an ALB, nginx, Caddy or an Ingress, and a client that ignored the
+forwarded headers there would not report *nothing* — it would confidently report an internal
+hostname on an internal port. `host` is caller-controlled either way (it has always come from
+the `Host` header), and none of these three values is ever used as an identity or
+authorization key, so the worst case is a wrong *suggestion* that an admin has to approve.
+
 ### `configure` block example
 
 ```ruby
@@ -120,16 +150,28 @@ export ENDPOINTBLANK_ENV=staging
 
 ### Authorization
 
-`EndPointBlank::Authorization.header(hostname = nil)` builds the outbound `Authorization` header
-used by the gem's own HTTP calls: a cached `Bearer` token for `hostname` when one is available
-(via `EndPointBlank::AccessTokens`), otherwise `Basic` credentials built from `client_id` /
-`client_secret`.
+`EndPointBlank::Authorization.header(base_url = nil)` builds the outbound `Authorization` header
+used by the gem's own HTTP calls: a cached `Bearer` token covering `base_url` when one is
+available (via `EndPointBlank::AccessTokens`), otherwise `Basic` credentials built from
+`client_id` / `client_secret` -- which covers both giving no target and a token that could not
+be obtained.
 
 ```ruby
-EndPointBlank::Authorization.header               # => "Basic ..."
-EndPointBlank::Authorization.header("api.example.com") # => "Bearer ..." if a token is cached
+EndPointBlank::Authorization.header # => "Basic ..."
+
+# Pass the URL you are about to call, NOT a hostname.
+# Strip any query string or fragment first -- intake rejects both.
+EndPointBlank::Authorization.header("https://api.example.com/orders") # => "Bearer ..." if a token is cached
 ```
 
+The argument is the URL you are about to call. intake matches it against registered base URLs by
+longest path prefix, so you need not know how the target registered itself -- `header` for
+`https://api.example.com/orders/42` reuses a token already cached for
+`https://api.example.com/orders`. `EndPointBlank::AccessTokens` caches one token per base URL
+intake resolves to, not one per process, so a service that calls several targets holds a token
+for each. A URL that does not match character-for-character (a different case, a query string,
+an unregistered path) simply misses and mints a new token -- it never guesses.
+
 Under Rails, protect an inbound endpoint by including the `Authorized` concern in a controller —
 it calls `EndPointBlank::Commands::EndpointAuthorize.authorize(request)` before the action, and
 raises `EndPointBlank::UnauthorizedError` (which you can rescue with
@@ -143,8 +185,17 @@ end
 
 `EndPointBlank::Commands::EndpointAuthorize.authorize` sends the request's path, HTTP method,
 inbound `Authorization` header, app name, resolved endpoint version, and remote IP to
-`#{base_url}/api/authorize`, and caches a positive (201) result for `cache_ttl` seconds via
-`EndPointBlank::Commands::AuthenticationCache`.
+`#{base_url}/api/authorize`, authenticating itself to intake with `Basic`, and caches a positive
+(201) result for `cache_ttl` seconds via `EndPointBlank::Commands::AuthenticationCache`. It never
+mints or presents a Bearer token for this call: intake already holds this service's own
+credential, so exchanging one to present it back would buy nothing.
+
+**Behavior change:** `target_hostname` on the authorize call now comes from the `Host` header
+only. It previously came from `request.host`, which reads the last `X-Forwarded-Host` hop. If
+your app sits behind a proxy that **rewrites** `Host` (nginx's default; Caddy and most ALBs
+preserve it) and you registered the external hostname in the portal, either update the
+registered hostname to the internal one the app now reports, or configure the proxy to preserve
+`Host`. Deployments where `Host` and `X-Forwarded-Host` agree are unaffected.
 
 ### Error reporting
 

data/deploy

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+gem build end_point_blank.gemspec
+
+gem push end_point_blank-*.gem

data/end_point_blank.gemspec

@@ -34,8 +34,13 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   spec.add_dependency "excon", "~> 1.0"
-  spec.add_dependency "rack"
-  spec.add_dependency "rexml"
+  # rack and rexml carried no floor at all, which let a host application resolve
+  # them to versions with known advisories. These are the lowest releases clear
+  # of every advisory published against each gem, not the newest available — a
+  # library should state the oldest version it will vouch for, not force the
+  # host to the bleeding edge.
+  spec.add_dependency "rack", ">= 3.2.6"
+  spec.add_dependency "rexml", ">= 3.3.9"
   # Base64 was removed from Ruby's default gems as of 3.4; Authorization
   # uses it for the Basic-auth header, so declare it explicitly.
   spec.add_dependency "base64"

data/lib/end_point_blank/access_tokens.rb

@@ -4,69 +4,217 @@ require 'singleton'
 require "time"
 
 module EndPointBlank
-  # Thread-safe singleton cache for storing access tokens per hostname
+  # Thread-safe singleton holding this process's access tokens, one per
+  # application environment.
+  #
+  # A token is cached under the canonical base URL intake resolved the
+  # request to -- not under the URL the caller supplied. A caller asks for the
+  # URL it is about to call; intake answers with the base URL of the
+  # environment that URL belongs to, and subsequent calls anywhere under that
+  # base URL reuse the entry.
+  #
+  # Lookup is a plain exact-or-path-prefix comparison, with the longest match
+  # winning. The SDK deliberately does not normalize: intake owns that rule,
+  # and a miss costs one extra request rather than a wrong answer.
+  #
+  # A lookup has to scan the keys, and the fast path deliberately does not
+  # take the mutex, so every write **replaces** the entries Hash instead of
+  # mutating it. A reader then takes one atomic read of @entries and iterates
+  # something nobody can change underneath it. Mutating in place would risk
+  # "can't add a new key into hash during iteration" as soon as one thread
+  # minted a token for a second target while another was doing a lookup.
   class AccessTokens
     include Singleton
 
-    def initialize()
-      @tokens = {}
-      @mutexes = {}
+    # Replace a token this far ahead of its expiry. An expired token can never
+    # be revived, only replaced, so going early is what keeps an in-flight
+    # request from carrying one that dies before it lands.
+    REFRESH_WINDOW = 120
+
+    # exists? is used to decide whether a caller can proceed without a round
+    # trip, so it answers no while there is barely any life left.
+    PRESENCE_WINDOW = 30
+
+    # How long to hold a token whose expiry the intake sent unreadably.
+    DEFAULT_LIFETIME = 3600
+
+    def initialize
+      @mutex = Mutex.new
+      @entries = {}
     end
 
-    def self.token(arg)
-      instance.token(arg)
+    def self.token(base_url)
+      instance.token(base_url)
     end
 
-    # Retrieve or generate an access token for the given hostname
-    # @param hostname [String] The hostname for which to retrieve the token
-    # @return [String, nil] The access token or nil if generation fails
-    def token(arg)
-      hostname = arg.downcase
-      @mutexes[hostname] ||= Mutex.new
-      @mutexes[hostname].synchronize do
-        # Return cached token if it exists and is not expired
-        return @tokens[hostname][:token] if @tokens.key?(hostname) && @tokens[hostname][:expired_at] > Time.now + 120
-
-        # Fetch new token
-        payload = Commands::GenerateAccessToken.token(hostname)
-
-        if payload && payload[:token]
-          payload[:expired_at] = Time.parse(payload[:expired_at])
-          @tokens[hostname] = payload
+    # Retrieve a token covering base_url, generating one if no usable entry
+    # covers it.
+    # @param base_url [String] the URL you are about to call, with any query
+    #   string and fragment removed. It is sent verbatim; intake normalizes it
+    #   and matches it against registered base URLs by longest path prefix.
+    # @return [String, nil] The access token string, or nil if generation
+    #   failed -- which includes a response that carried a token but no
+    #   base_url.
+    def token(base_url)
+      entry = match(base_url)
+      return entry[:token] if usable?(entry)
+
+      @mutex.synchronize do
+        # Another caller may have filled it while this one waited.
+        entry = match(base_url)
+        return entry[:token] if usable?(entry)
+
+        payload = Commands::GenerateAccessToken.token(base_url)
+
+        # The key is what intake resolved to, and only that. There is no
+        # fallback to the requested URL: that would key on the resource the
+        # caller happened to ask about, so a service walking /orders/1,
+        # /orders/2, /orders/3 would mint and store a token per resource, and
+        # nothing here evicts. Without a base URL the right application
+        # cannot be found, so no token is handed back either.
+        key = payload && payload[:base_url]
+
+        if payload && payload[:token] && key
+          # The match that led here may have resolved under a different key
+          # than the one intake just returned -- an environment's base URL
+          # can change to a shorter path in the portal. Drop that stale key
+          # when it differs from the fresh one, or it goes on shadowing it:
+          # being the longer of the two, it keeps winning "longest match
+          # wins", keeps failing usable?, and keeps forcing a mint on every
+          # call until the process restarts. The failure branch below already
+          # does the equivalent for a match that turned out unusable; this is
+          # the same cleanup for a match that turned out to have moved.
+          stale = match_key(base_url, @entries)
+          new_entries = @entries.merge(
+            key => { token: payload[:token], expired_at: parse_expiry(payload[:expired_at]) }.freeze
+          )
+          new_entries = new_entries.reject { |k, _| k == stale } if stale && stale != key
+          @entries = new_entries.freeze
           payload[:token]
         else
-          EndPointBlank.logger.error "Failed to generate access token for #{hostname}: #{payload&.fetch('error')}"
+          # A failed refresh must not leave an expiring token behind claiming
+          # to be usable -- callers would keep presenting it right up to the
+          # 401. Only the entry that covers this URL goes: the longest match
+          # is the one that was just found unusable, so a shorter, still-good
+          # entry survives.
+          stale = match_key(base_url, @entries)
+          @entries = @entries.reject { |k, _| k == stale }.freeze if stale
+
+          EndPointBlank.logger.error "Failed to generate access token for #{base_url}: #{failure_reason(payload)}"
           nil
         end
       end
     end
 
-    # Clear all tokens from the cache
-    # @return [Hash] Empty hash
-    def clear(arg)
-      @mutexes.keys.each do |hostname|
-        @mutexes[hostname].synchronize do
-          @tokens.delete(hostname)
-        end
+    # Discard every held token
+    # @return [nil]
+    def clear
+      @mutex.synchronize { @entries = {}.freeze }
+    end
+
+    # Discard the held token, but only if it is still the one the caller had
+    #
+    # Every request in flight when a token is rejected reports the same stale
+    # value. Only the first of them should cause an exchange -- the rest are
+    # holding a token that has already been replaced, and clearing on their
+    # behalf would discard a good token and stampede intake.
+    #
+    # The lookup is by token value because a rejected caller has a token, not
+    # a URL.
+    #
+    # @param stale_token [String, nil] the token the caller was rejected for;
+    #   ignored when it is no longer the one held for its base URL.
+    # @return [nil]
+    def invalidate(stale_token)
+      return if stale_token.nil?
+
+      @mutex.synchronize do
+        @entries = @entries.reject { |_, entry| entry[:token] == stale_token }.freeze
+      end
+    end
+
+    # Check whether a token covering base_url is held and is not about to
+    # expire
+    # @param base_url [String] the URL to check coverage for
+    # @return [Boolean]
+    def exists?(base_url)
+      entry = match(base_url)
+      !entry.nil? && entry[:expired_at] > Time.now + PRESENCE_WINDOW
+    end
+
+    private
+
+    # Returns the longest key in entries covering base_url, or nil.
+    #
+    # A nil or empty base_url never matches. An empty cache can't raise on
+    # one -- the loop body never runs -- so a non-empty cache must not either,
+    # or the same call succeeds or raises NoMethodError (nil has no
+    # start_with?) depending on unrelated traffic that happened to warm the
+    # cache first. Checking once, here, keeps every caller consistent for
+    # free: the lookup, the stale-entry cleanup on a failed refresh, and the
+    # stale-entry cleanup on a successful one.
+    #
+    # Deliberately not a port of intake's matcher: no normalization on either
+    # side. A caller that passes a non-canonical URL simply misses and mints
+    # again, which costs one HTTP call and is never a wrong answer.
+    #
+    # Takes entries as an explicit argument, rather than reading @entries
+    # itself, so the snapshot discipline is structural: every caller decides
+    # which snapshot is being scanned instead of this method reaching for
+    # whatever @entries happens to be at the moment it runs.
+    def match_key(base_url, entries)
+      return nil if base_url.nil? || base_url.empty?
+
+      best = nil
+      entries.each_key do |key|
+        next unless base_url == key || base_url.start_with?("#{key}/")
+
+        best = key if best.nil? || key.length > best.length
       end
+      best
     end
 
-    # Remove token for a specific hostname
-    # @param hostname [String] The hostname for which to remove the token
-    # @return [Object, nil] The removed token data or nil if not found
-    def remove(arg)
-      hostname = arg.downcase
-      @mutexes[hostname].synchronize do
-        @tokens.delete(hostname)
+    def match(base_url)
+      entries = @entries # One atomic read; writes replace, never mutate.
+      key = match_key(base_url, entries)
+      key && entries[key]
+    end
+
+    def usable?(entry)
+      !entry.nil? && entry[:expired_at] > Time.now + REFRESH_WINDOW
+    end
+
+    # Why a mint produced no usable token, for the log.
+    def failure_reason(payload)
+      return "no response" unless payload.is_a?(Hash)
+      return payload[:error] if payload[:error]
+
+      if payload[:token]
+        # Distinct from a rejected request: intake's base_url is NOT NULL, and
+        # it answers 422 rather than minting when the caller's URL resolves to
+        # no environment. A token with no base_url is a broken server.
+        return "response carried a token but no base_url"
       end
+
+      "no token in response"
     end
 
-    # Check if a valid token exists for a given hostname
-    # @param hostname [String] The hostname to check
-    # @return [Boolean] True if a valid token exists, false otherwise
-    def exists?(arg)
-      hostname = arg.downcase
-      @tokens.key?(hostname) && @tokens[hostname][:expired_at] > Time.now + 30
+    # Time.parse raises on anything it cannot read — an ArgumentError for a
+    # string it fails to understand, a TypeError for a value that is not a
+    # string at all, including the nil left by a missing key. This runs inside
+    # the mutex on the path a caller's request goes through, so a malformed
+    # timestamp from the intake came out of Authorization.header and into the
+    # host application's request.
+    #
+    # An hour is a guess, but a working one. Treating the token as unusable
+    # instead would mean an exchange on every inbound request for as long as
+    # the far end misbehaves. There is no retry here if the token dies sooner
+    # than the guess -- invalidate has no caller on this path -- so a bad
+    # guess means 401s until the cache's own expiry-based refresh catches up.
+    def parse_expiry(value)
+      Time.parse(value.to_s)
+    rescue ArgumentError, TypeError
+      Time.now + DEFAULT_LIFETIME
     end
   end
 end