fix(auth): exchange any non-JWT credential, not just hd_

Author: zfarrell

hotdata/_auth.py

@@ -13,10 +13,11 @@
 
 Key behaviors:
 
-* **Pass-through** -- only ``hd_`` API tokens are exchanged. A credential that
-  already looks like a JWT (``eyJ`` prefix), or any other non-``hd_`` value
-  (local/dev/test credentials), is returned unchanged and never exchanged, so
-  local setups and the rollout window keep working.
+* **Pass-through** -- a credential that already looks like a JWT (``eyJ``
+  prefix, matching the Gateway's own ``^Bearer eyJ.*`` detection) is returned
+  unchanged and never exchanged. Every other (opaque) credential is treated as
+  an API token and exchanged; set ``HOTDATA_DISABLE_JWT_EXCHANGE`` to force a
+  raw, non-JWT credential through as-is (local/dev setups, rollback).
 * **Opt-out** -- if ``HOTDATA_DISABLE_JWT_EXCHANGE`` is set to any truthy value,
   the credential is always returned as-is (hard escape hatch for rollout).
 * **In-memory cache only** -- no disk writes. The server already de-duplicates
@@ -44,7 +45,6 @@
 _LEEWAY = 30          # refresh when <30s of life remains
 _TIMEOUT = 30.0       # seconds -- never let a stalled token endpoint hang every request
 _CLIENT_ID = "hotdata-python-sdk"
-_API_TOKEN_PREFIX = "hd_"   # only credentials with this prefix are exchanged
 
 # Env var that disables exchange entirely (any truthy value). Used as a hard
 # escape hatch during the rollout window and for local/dev setups.
@@ -56,7 +56,7 @@
 
 
 class TokenExchangeError(Exception):
-    """Raised when an ``hd_`` API token cannot be exchanged for a JWT.
+    """Raised when an API token cannot be exchanged for a JWT.
 
     Surfacing ``invalid_grant`` (expired/revoked API token) here keeps the
     failure clear instead of a confusing downstream 401.
@@ -123,9 +123,10 @@ def _pool_from_config(configuration):
 class _TokenManager:
     """Exchanges an API token for short-lived JWTs and keeps them fresh.
 
-    Only ``hd_`` API tokens are exchanged; anything else (raw ``eyJ`` JWTs,
-    local/dev/test credentials) is passed through unchanged, as is any
-    credential when ``HOTDATA_DISABLE_JWT_EXCHANGE`` is set.
+    A credential that already looks like a JWT (``eyJ`` prefix) is passed
+    through unchanged, as is any credential when
+    ``HOTDATA_DISABLE_JWT_EXCHANGE`` is set; every other (opaque) API token is
+    exchanged.
     """
 
     def __init__(self, credential, configuration, pool=None):
@@ -143,12 +144,14 @@ def _needs_exchange(self):
         # send the credential as-is, never touching the token endpoint.
         if os.environ.get(_DISABLE_ENV):
             return False
-        # Exchange only real ``hd_`` API tokens. Everything else is passed
-        # through untouched: raw JWTs (``eyJ`` prefix) are already what we want
-        # on the wire, and non-``hd_`` values (local/dev/test credentials) must
-        # not be sent to the token endpoint -- doing so would break local setups
-        # and the rollout window (see the design's pass-through edge case).
-        return isinstance(self._credential, str) and self._credential.startswith(_API_TOKEN_PREFIX)
+        # A compact JWT always starts with "eyJ" (base64 of '{"'), matching the
+        # Gateway's own ``^Bearer eyJ.*`` detection -- those already are what we
+        # want on the wire, so pass them through. Everything else is an opaque
+        # API token to be exchanged. (Hotdata API tokens are bare hex; the
+        # ``hd_`` prefix seen in docs/comments is cosmetic and not enforced by
+        # the server, so we must not gate on it.) Use HOTDATA_DISABLE_JWT_EXCHANGE
+        # to force a raw, non-JWT credential through unchanged (local/dev).
+        return isinstance(self._credential, str) and not self._credential.startswith("eyJ")
 
     def bearer_value(self):
         """Return a live JWT (exchanging + caching), or the credential as-is.

tests/test_arrow.py

@@ -82,6 +82,11 @@ def _install_fake_response(
 ) -> None:
     """Replace RESTClientObject.request with a stub that records the call."""
 
+    # The api_key used here ("test-key") is a dummy, not a real token. Disable
+    # transparent JWT exchange so auth_settings() does not try to mint one
+    # against a non-existent endpoint when the (stubbed) request is built.
+    monkeypatch.setenv("HOTDATA_DISABLE_JWT_EXCHANGE", "1")
+
     from hotdata import rest
 
     def fake_request(

tests/test_auth.py

@@ -7,8 +7,8 @@
 
 They verify the pinned public contract:
 
-* first mint     -- an ``hd_`` credential POSTs an ``api_token`` grant to
-                    ``/v1/auth/jwt`` (form-encoded, correct Content-Type and
+* first mint     -- an opaque (non-JWT) credential POSTs an ``api_token`` grant
+                    to ``/v1/auth/jwt`` (form-encoded, correct Content-Type and
                     ``client_id``) and returns the minted ``access_token``;
 * cache hit      -- a second ``bearer_value()`` within TTL does not re-hit the
                     pool;
@@ -400,35 +400,45 @@ def test_deepcopied_manager_credential_still_mints() -> None:
 
 
 # --------------------------------------------------------------------------
-# Non-hd_ credentials pass through (only real API tokens are exchanged)
+# Opaque (non-JWT) credentials are exchanged -- the prefix is not gated
 # --------------------------------------------------------------------------
 
 
-def test_non_hd_credential_is_passed_through_unchanged() -> None:
-    """Only ``hd_`` API tokens are exchanged. A non-``hd_`` value (e.g. a
-    local/dev/test credential) must be sent as-is and never hit the token
-    endpoint -- otherwise local setups and the rollout window break."""
-    pool = _FakePool([_mint_response()])
-    mgr = _TokenManager("test-key", _config(), pool=pool)
+def test_bare_hex_token_is_exchanged() -> None:
+    """Hotdata API tokens are bare hex with no ``hd_`` prefix (the prefix in
+    the docs is cosmetic and not enforced by the server). Any opaque, non-JWT
+    credential must therefore be exchanged, not passed through."""
+    raw = "8a4bfd9cfa6926344f770d6b9a093c2b559dafc4de2a69137acb93e7e9821c7b"
+    pool = _FakePool([_mint_response(access_token="eyJ.minted.jwt")])
+    mgr = _TokenManager(raw, _config(), pool=pool)
 
-    assert mgr.bearer_value() == "test-key"
-    assert pool.calls == []
+    assert mgr.bearer_value() == "eyJ.minted.jwt"
+    assert len(pool.calls) == 1
+    assert _form(pool.calls[0]["body"])["api_token"] == [raw]
 
 
-def test_configuration_with_non_hd_key_never_mints() -> None:
-    """End-to-end regression for the predicate: building a Configuration with a
-    non-``hd_`` key (as the arrow tests do) must not trigger a network mint when
-    ``auth_settings()`` reads ``api_key``."""
-    cfg = Configuration(host="https://api.hotdata.test", api_key="test-key")
-    # Wire a recording pool in; if exchange were (wrongly) attempted it would
-    # show up here instead of trying a real socket.
-    pool = _FakePool([_mint_response()])
+def test_configuration_exchanges_bare_token_then_opt_out_passes_through(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """End-to-end at the Configuration level: a bare token is exchanged so
+    ``auth_settings()`` carries the minted JWT; with the opt-out env var set the
+    raw token is sent unchanged (the arrow-test style dummy-key setup)."""
+    raw = "8a4bfd9c0bare0token"
+
+    # Exchange path: auth_settings() carries the minted JWT, not the raw token.
+    pool = _FakePool([_mint_response(access_token="eyJ.live.jwt")])
+    cfg = Configuration(host="https://api.hotdata.test", api_key=raw)
     cfg._token_manager._pool = pool
+    assert _bearer_from(cfg.auth_settings()) == "Bearer eyJ.live.jwt"
+    assert len(pool.calls) == 1
 
-    assert cfg.api_key == "test-key"
-    bearer = _bearer_from(cfg.auth_settings())
-    assert bearer == "Bearer test-key"
-    assert pool.calls == []
+    # Opt-out path: same raw token, exchange disabled -> sent as-is, no mint.
+    monkeypatch.setenv("HOTDATA_DISABLE_JWT_EXCHANGE", "1")
+    pool2 = _FakePool([_mint_response()])
+    cfg2 = Configuration(host="https://api.hotdata.test", api_key=raw)
+    cfg2._token_manager._pool = pool2
+    assert _bearer_from(cfg2.auth_settings()) == f"Bearer {raw}"
+    assert pool2.calls == []
 
 
 # --------------------------------------------------------------------------