fix(auth): tell a replayed-and-dead token apart from a skewed clock

An elapsed claim has two causes and they want opposite answers. The previous
commit treated both as skew.

  replayed    the server keeps handing back one cached token and its `exp` has
              finally passed. The token really is dead. Falling back to
              `expires_in` gives a corpse a fresh 300s lease -- the pre-fix
              behaviour -- and leaves the 401 retry to pay a round trip that a
              proactive mint would have avoided.

  first seen  the clocks disagree. The server validates `exp` against its own
              clock, so the token is fine and only this client disbelieves it.
              Honouring the claim pins `_exp` in the past and runs both grants on
              every request forever.

`_replayed`, set two lines above, already separates them: it is True only for a
token this manager already held, i.e. one whose claim it accepted as FUTURE on an
earlier mint -- so the clock cannot be the explanation the second time. Under skew
each mint returns a distinct token, so the fallback still applies.

The union -- skewed clock AND replaying server -- takes the honour-the-claim
branch and goes back to both grants per request. Traded knowingly: rarer than
either alone, and the 401 retry still covers it.

The elapsed-claim path had coverage only in the skew direction; the replay test
stopped at a claim 10s in the future, so nothing pinned down what happened when
that token finally elapsed. The new test drives `_mint` directly rather than
waiting out the first fallback's 300s lease, since that lease is the thing under
test and not a precondition worth sleeping for.

234 passed. Live endpoint tracks exactly (300/300 ... 290/290).

Author: anoop-narang

hotdata/_auth.py

@@ -367,16 +367,33 @@ def _mint(self, params):
         now = time.time()
         by_expires_in = now + expires_in
         claim = _exp_from_jwt(token)
-        if claim is not None and claim > now:
+        if claim is not None and (claim > now or self._replayed):
             self._exp = min(by_expires_in, claim)
         else:
-            # No readable claim, or one ALREADY ELAPSED when the mint returned.
-            # An elapsed claim means the clocks disagree, not that the server
-            # handed back a corpse -- it validates `exp` against its own clock, so
-            # the token is fine and only this client disbelieves it. Honouring the
-            # claim here would set `_exp` permanently in the past, and every
-            # request would then run both grants forever. `expires_in` is always
-            # in the future, which is what makes it the safe fallback for skew.
+            # No readable claim, or one already elapsed on a token we had NOT seen
+            # before. Two causes produce an elapsed claim and they want opposite
+            # answers, so `_replayed` -- set just above -- separates them:
+            #
+            #   replayed  the server keeps handing back one cached token, and its
+            #             `exp` has finally passed. The token really is dead.
+            #             Honour the claim: this manager accepted the same claim as
+            #             FUTURE on an earlier mint, so the clock is not the
+            #             explanation, and pretending otherwise would put `_exp` at
+            #             `now + 300` on a corpse -- the pre-fix behaviour, leaving
+            #             the 401 retry to pay a round trip that a proactive mint
+            #             would have avoided.
+            #
+            #   first seen  the clocks disagree. The server validates `exp` against
+            #             its own clock, so the token is fine and only this client
+            #             disbelieves it. Honouring the claim would pin `_exp` in
+            #             the past and run both grants on every request forever.
+            #             `expires_in` is always in the future, which is what makes
+            #             it the safe fallback.
+            #
+            # A skewed clock AND a replaying server together fall to the first
+            # branch, i.e. back to both grants per request. That union is the case
+            # being traded away, knowingly: it is rarer than either alone and the
+            # 401 retry still covers it.
             self._exp = by_expires_in
         self._refresh = data.get("refresh_token") or self._refresh
         return True

tests/test_auth.py

@@ -1213,3 +1213,27 @@ def test_a_claim_already_elapsed_is_declined_so_a_skewed_clock_still_works() ->
     mgr.bearer_value()
     assert len(pool.calls) == calls, "kept minting under skew"
 
+
+def test_a_replayed_token_that_finally_elapsed_is_not_given_a_fresh_lease() -> None:
+    """The other cause of an elapsed claim, which wants the opposite answer to
+    skew. When the server keeps replaying one cached token, its `exp` eventually
+    passes for real. Falling back to `expires_in` there would put `_exp` at
+    `now + 300` on a corpse -- the pre-fix behaviour -- and leave the 401 retry to
+    pay a round trip a proactive mint would have avoided.
+
+    Drives `_mint` directly: reaching this through `bearer_value` would need the
+    first fallback's 300s lease to run down first, which is the thing under test,
+    not a precondition worth sleeping for.
+    """
+    dead = _jwt_with_exp(-5, jti="replayed-and-dead")
+    pool = _FakePool([_mint_response(access_token=dead, expires_in=300)])
+    mgr = _TokenManager("hd_secret_token", _config(), pool=pool)
+    grant = {"grant_type": "api_token", "api_token": "hd_secret_token"}
+
+    mgr._mint(dict(grant))          # first sight: elapsed but unseen -> skew branch
+    assert mgr._replayed is False
+    assert mgr._exp - time.time() > 200, "first sight should fall back to expires_in"
+
+    mgr._mint(dict(grant))          # same token back -> a known replay
+    assert mgr._replayed is True
+    assert mgr._exp - time.time() < 0, "gave a dead replayed token a fresh lease"