feat: evict bearer token on a 401 challenge

BearerTokenAuthStep only refreshed its cached token on the local expiry
margin. When a server revokes a token before its advertised expiry, the
step kept stamping the rejected token until the margin elapsed, so every
request in that window failed with a 401.

Override authorizeRequestOnChallenge so a 401 carrying WWW-Authenticate
evicts the rejected token and re-stamps the request with a freshly
fetched one, driving AuthStep's existing single retry with a new
credential. Using the in-step hook (rather than throwing a retryable
exception) means the retry is not gated by request idempotency, so a
non-idempotent POST is re-authenticated too.

Eviction is scoped to the token that actually produced the 401 (matched
against the request's Authorization header) and runs under the same lock
as the refresh path, so a token a concurrent request already refreshed
is preserved rather than clobbered. This is an additional eviction
trigger layered on top of the expiry-margin check, which is unchanged.

Author: OmarAlJarrah

sdk-core/api/sdk-core.api

@@ -755,6 +755,7 @@ public class org/dexpace/sdk/core/http/pipeline/steps/BearerTokenAuthStep : org/
 	public fun <init> (Lorg/dexpace/sdk/core/http/auth/BearerTokenProvider;Ljava/util/List;Ljava/time/Duration;Lorg/dexpace/sdk/core/util/Clock;)V
 	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/auth/BearerTokenProvider;Ljava/util/List;Ljava/time/Duration;Lorg/dexpace/sdk/core/util/Clock;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	protected fun authorizeRequest (Lorg/dexpace/sdk/core/http/request/Request;)Lorg/dexpace/sdk/core/http/request/Request;
+	protected fun authorizeRequestOnChallenge (Lorg/dexpace/sdk/core/http/request/Request;Lorg/dexpace/sdk/core/http/response/Response;)Lorg/dexpace/sdk/core/http/request/Request;
 }
 
 public final class org/dexpace/sdk/core/http/pipeline/steps/DefaultAsyncInstrumentationStep : org/dexpace/sdk/core/http/pipeline/AsyncHttpStep {

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/pipeline/steps/BearerTokenAuthStep.kt

@@ -11,6 +11,7 @@ import org.dexpace.sdk.core.http.auth.BearerToken
 import org.dexpace.sdk.core.http.auth.BearerTokenProvider
 import org.dexpace.sdk.core.http.common.HttpHeaderName
 import org.dexpace.sdk.core.http.request.Request
+import org.dexpace.sdk.core.http.response.Response
 import org.dexpace.sdk.core.util.Clock
 import java.time.Duration
 import java.util.concurrent.locks.ReentrantLock
@@ -37,6 +38,19 @@ import kotlin.concurrent.withLock
  * to decide when to refresh pre-emptively (default 30 seconds). A token whose `expiresAt`
  * is `now + 29s` with the default margin is considered expired and is refreshed.
  *
+ * ## Eviction on 401
+ *
+ * The refresh margin only covers *local* expiry. A server may revoke a token before its
+ * advertised expiry, and the cached token would otherwise keep being stamped until the
+ * margin elapsed. To handle this, [authorizeRequestOnChallenge] evicts the rejected token
+ * on a 401 + `WWW-Authenticate` response and re-stamps the request with a freshly fetched
+ * one, so the single retry driven by [AuthStep] carries a new credential. Eviction is an
+ * *additional* trigger layered on top of the margin check — it does not change pre-emptive
+ * refresh. Only the token that produced the 401 is evicted; a token a concurrent request
+ * already refreshed in the meantime is left in place. The retry runs regardless of HTTP
+ * method (the in-step hook is not gated by retry-safety), so a non-idempotent POST is
+ * re-authenticated too.
+ *
  * ## Errors from [provider]
  *
  *  - Throws → propagated. The exception is **not** cached, so a subsequent request
@@ -46,8 +60,9 @@ import kotlin.concurrent.withLock
  *
  * ## Open for subclassing
  *
- * Users wanting to override [authorizeRequestOnChallenge] (e.g. force a token refresh on
- * 401) can extend this class.
+ * Eviction-on-401 is built in. Users wanting to customise challenge handling further (e.g.
+ * inspect the `WWW-Authenticate` scheme before deciding to refresh) can override
+ * [authorizeRequestOnChallenge].
  *
  * Thread-safety: see Caching above.
  * Cancellation: token fetch may block; the [provider] is expected to respect interrupts.
@@ -72,6 +87,40 @@ public open class BearerTokenAuthStep
                 .build()
         }
 
+        /**
+         * On a 401 challenge, evict the token that was just rejected and re-stamp [request]
+         * with a freshly fetched one so [AuthStep]'s single retry carries a new credential.
+         *
+         * Eviction is scoped to the exact token that produced the 401 (matched against the
+         * `Authorization` header [request] carried): if a concurrent request already refreshed
+         * the cache, that newer token is preserved and reused for the retry rather than being
+         * discarded. The subsequent [currentToken] call then re-fetches only when the cache is
+         * actually empty, so a 401 storm across threads still funnels through the same
+         * double-checked-locking fetch as the expiry-margin path.
+         */
+        override fun authorizeRequestOnChallenge(
+            request: Request,
+            response: Response,
+        ): Request {
+            evictRejectedToken(request.headers.get(HttpHeaderName.AUTHORIZATION))
+            return authorizeRequest(request)
+        }
+
+        /**
+         * Clears [cachedToken] iff it is still the token whose stamped header is [rejectedHeader].
+         * Guarded by the same [lock] as the refresh path so the read-compare-clear is atomic
+         * against a concurrent refresh.
+         */
+        private fun evictRejectedToken(rejectedHeader: String?) {
+            if (rejectedHeader == null) return
+            lock.withLock {
+                val current = cachedToken ?: return
+                if ("Bearer ${current.token}" == rejectedHeader) {
+                    cachedToken = null
+                }
+            }
+        }
+
         private fun currentToken(): BearerToken {
             // Fast path: lock-free volatile read; return the cached token if it's still valid.
             cachedToken?.takeIf { !it.isExpiredAt(clock.now(), refreshMargin) }?.let { return it }

sdk-core/src/test/kotlin/org/dexpace/sdk/core/http/pipeline/steps/AuthStepTest.kt

@@ -519,15 +519,16 @@ class AuthStepTest {
     // ----------------- 401 + WWW-Authenticate handling -----------------
 
     @Test
-    fun `401 with WWW-Authenticate returns the 401 unchanged by default`() {
-        val provider = BearerTokenProvider { _, _ -> BearerToken("tk", null) }
+    fun `401 with WWW-Authenticate returns the 401 unchanged when the step does not override the challenge hook`() {
+        // KeyCredentialAuthStep does not override authorizeRequestOnChallenge, so it exercises
+        // the AuthStep base default (returns null → no retry). The 401 surfaces unchanged.
         val fake =
             FakeHttpClient()
                 .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
 
         val pipeline =
             HttpPipelineBuilder(fake)
-                .append(BearerTokenAuthStep(provider, listOf("scope")))
+                .append(KeyCredentialAuthStep(KeyCredential("k")))
                 .build()
 
         val response = pipeline.send(getHttpsRequest())

sdk-core/src/test/kotlin/org/dexpace/sdk/core/http/pipeline/steps/BearerTokenAuthStepTest.kt

@@ -13,10 +13,15 @@ import org.dexpace.sdk.core.http.common.HttpHeaderName
 import org.dexpace.sdk.core.http.pipeline.HttpPipelineBuilder
 import org.dexpace.sdk.core.http.request.Method
 import org.dexpace.sdk.core.http.request.Request
+import org.dexpace.sdk.core.http.request.RequestBody
+import org.dexpace.sdk.core.io.Io
 import org.dexpace.sdk.core.testing.FakeHttpClient
 import org.dexpace.sdk.core.testing.FixedClock
+import org.dexpace.sdk.io.OkioIoProvider
 import java.time.Duration
 import java.time.Instant
+import java.util.concurrent.atomic.AtomicInteger
+import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFailsWith
@@ -28,6 +33,13 @@ class BearerTokenAuthStepTest {
     private val nowInstant: Instant = Instant.parse("2026-01-01T12:00:00Z")
     private val clock = FixedClock(nowInstant)
 
+    @BeforeTest
+    fun setUp() {
+        // The 401-challenge retry path closes the 401 response body; tests that exercise it
+        // need an installed IoProvider so body materialization succeeds.
+        Io.installProvider(OkioIoProvider)
+    }
+
     // ---- B14: fresh-token validation does NOT apply refreshMargin ----
 
     /**
@@ -172,11 +184,128 @@ class BearerTokenAuthStepTest {
         assertEquals(2, calls, "provider must have been called again after prior exception")
     }
 
+    // ---- Evict-on-401 ----
+
+    @Test
+    fun `401 challenge evicts the cached token and the retry carries a freshly fetched one`() {
+        // A non-expiring token would normally be cached forever (no expiry margin ever fires).
+        // The server rejects the first attempt with a 401 + WWW-Authenticate; the step must
+        // evict the stale token and re-fetch so the single retry carries the fresh credential.
+        val fetches = AtomicInteger(0)
+        val provider =
+            BearerTokenProvider { _, _ ->
+                BearerToken("token-${fetches.incrementAndGet()}", futureExpiry)
+            }
+        val fake =
+            FakeHttpClient()
+                .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
+                .enqueue { status(200) }
+        val pipeline =
+            HttpPipelineBuilder(fake)
+                .append(BearerTokenAuthStep(provider, listOf("scope"), clock = clock))
+                .build()
+
+        val response = pipeline.send(getRequest())
+
+        assertEquals(200, response.status.code)
+        assertEquals(2, fake.callCount, "exactly one retry after the 401")
+        assertEquals(2, fetches.get(), "the 401 must trigger a re-fetch (eviction), not reuse the cached token")
+        // First attempt carries the stale token; the retry carries the freshly fetched one.
+        assertEquals("Bearer token-1", fake.requests[0].headers.get(HttpHeaderName.AUTHORIZATION))
+        assertEquals("Bearer token-2", fake.requests[1].headers.get(HttpHeaderName.AUTHORIZATION))
+    }
+
+    @Test
+    fun `401 eviction works for a non-idempotent POST`() {
+        // The in-step challenge hook is NOT gated by retry-safety, so a POST (non-idempotent)
+        // still re-authenticates after a 401. A replayable body lets the retry re-send.
+        val fetches = AtomicInteger(0)
+        val provider =
+            BearerTokenProvider { _, _ ->
+                BearerToken("token-${fetches.incrementAndGet()}", futureExpiry)
+            }
+        val fake =
+            FakeHttpClient()
+                .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
+                .enqueue { status(200) }
+        val pipeline =
+            HttpPipelineBuilder(fake)
+                .append(BearerTokenAuthStep(provider, listOf("scope"), clock = clock))
+                .build()
+
+        val response = pipeline.send(postRequest())
+
+        assertEquals(200, response.status.code)
+        assertEquals(2, fake.callCount, "the POST must be retried once after re-authentication")
+        assertEquals(2, fetches.get())
+        assertEquals("Bearer token-2", fake.requests[1].headers.get(HttpHeaderName.AUTHORIZATION))
+    }
+
+    @Test
+    fun `after a 401 eviction the next independent request still sees the refreshed token cached`() {
+        // The retry re-fetches and re-caches; a subsequent unrelated request must reuse that
+        // refreshed token rather than fetching a third time.
+        val fetches = AtomicInteger(0)
+        val provider =
+            BearerTokenProvider { _, _ ->
+                BearerToken("token-${fetches.incrementAndGet()}", futureExpiry)
+            }
+        val fake =
+            FakeHttpClient()
+                .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
+                .enqueue { status(200) }
+                .enqueue { status(200) }
+        val pipeline =
+            HttpPipelineBuilder(fake)
+                .append(BearerTokenAuthStep(provider, listOf("scope"), clock = clock))
+                .build()
+
+        pipeline.send(getRequest()) // 401 → evict → retry with token-2
+        pipeline.send(getRequest()) // reuses cached token-2
+
+        assertEquals(2, fetches.get(), "the refreshed token is cached; no third fetch")
+        assertEquals("Bearer token-2", fake.requests[2].headers.get(HttpHeaderName.AUTHORIZATION))
+    }
+
+    @Test
+    fun `repeated 401s surface the second 401 without a second retry`() {
+        // The base AuthStep retries exactly once. If the freshly fetched token is ALSO rejected,
+        // the second 401 is surfaced as the operation result (no infinite refresh loop), and the
+        // provider is consulted once per attempt (twice total).
+        val fetches = AtomicInteger(0)
+        val provider =
+            BearerTokenProvider { _, _ ->
+                BearerToken("token-${fetches.incrementAndGet()}", futureExpiry)
+            }
+        val fake =
+            FakeHttpClient()
+                .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
+                .enqueue { status(401).header("WWW-Authenticate", "Bearer realm=\"x\"") }
+        val pipeline =
+            HttpPipelineBuilder(fake)
+                .append(BearerTokenAuthStep(provider, listOf("scope"), clock = clock))
+                .build()
+
+        val response = pipeline.send(getRequest())
+
+        assertEquals(401, response.status.code, "the second 401 is surfaced, not retried again")
+        assertEquals(2, fake.callCount)
+        assertEquals(2, fetches.get())
+    }
+
     // ---- Helpers ----
 
     private fun getRequest(): Request =
         Request.builder()
             .method(Method.GET)
             .url("https://api.example.com/resource")
             .build()
+
+    private fun postRequest(): Request =
+        Request.builder()
+            .method(Method.POST)
+            .url("https://api.example.com/resource")
+            // RequestBody.create(String) is replayable, so the non-idempotent retry can re-send.
+            .body(RequestBody.create("payload"))
+            .build()
 }