elva-cli 0.4.0__tar.gz → 0.5.0__tar.gz

elva_cli-0.5.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## Unreleased
+
+### Added
+- **Identify as a first-class refresh client (ELVA-200).** Every request now
+  sends `X-Elva-Client: cli` and a `User-Agent: elva-cli/<version>`. The refresh
+  and CLI-login exchanges carry the marker so the backend routes them on the
+  body-token path and, once its compatibility flag is turned off, does not
+  reject the CLI as an unmarked client.
+- **Refresh-and-retry on 401.** An idempotent request (GET/HEAD) that returns
+  401 on a token that looked valid now forces one refresh and retries once.
+  Non-idempotent requests (the spec upload) are never auto-replayed.
+- **Backoff on transient refresh failures.** A refresh that hits 429/5xx or a
+  network error is retried with backoff (1s/2s/4s) before surfacing as a
+  transient `ApiError` (exit 5); it never forces a re-login.
+
+### Changed
+- Refresh continues to happen proactively ~60s before the access token expires
+  and to persist the rotated token atomically (temp file + rename, 0600) before
+  the response is used — unchanged, but now covered by explicit tests.
+
+### Compatibility
+This version works with **both** the flagged and the unflagged backend:
+- While the backend keeps `AUTH_ALLOW_BODY_REFRESH_TOKEN` on, unmarked body
+  refreshes still work, so **older CLI versions keep working** too.
+- Once the backend turns that flag off (this CLI version being the minimum
+  supported), the server rejects unmarked and legacy ("family-less") refresh
+  tokens with `401 REFRESH_TOKEN_LEGACY`. This CLI maps that to
+  *"Your session has expired. Run `elva auth login` to sign in again."*
+  (exit code 3). **Older CLI versions stop working at that point** and users
+  must upgrade and re-login once.

{elva_cli-0.4.0 → elva_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Elva - CLI for Theneo Elva
 Project-URL: Homepage, https://getelva.ai
 Project-URL: Source, https://github.com/Theneo-Inc/theneo-elva-cli

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/auth/__init__.py

@@ -23,6 +23,7 @@ if TYPE_CHECKING:
         forget_stored_credentials,
         get_access_token,
         logout,
+        refresh_now,
         save_login,
         save_pat,
     )
@@ -34,6 +35,7 @@ __all__ = [
     "forget_stored_credentials",
     "get_access_token",
     "logout",
+    "refresh_now",
     "save_login",
     "save_pat",
 ]

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/auth/session.py

@@ -20,18 +20,20 @@ import contextlib
 import json
 import logging
 import os
+import time
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
 from elva_cli.auth.models import Credentials
 from elva_cli.auth.store import FileStore, KeyringStore, StoreUnavailableError, TokenStore
+from elva_cli.core.api.identity import client_headers
 from elva_cli.core.services.auth_result import LogoutResult as LogoutResult
 from elva_cli.core.services.auth_result import LogoutStatus as LogoutStatus
 from elva_cli.errors import ApiError, AuthError
 from elva_cli.settings import paths
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
 _logger = logging.getLogger(__name__)
 
@@ -41,6 +43,16 @@ _LOCK_FILE = "refresh.lock"
 _HTTP_TIMEOUT = 10
 _LOGOUT_TIMEOUT = 5
 
+# Backoff for a transiently-failing refresh (429 / 5xx / network): the initial
+# attempt plus retries sleeping these seconds between them, then give up with an
+# ApiError (transient, exit 5) - never a forced re-login.
+_REFRESH_BACKOFF_SECONDS = (1.0, 2.0, 4.0)
+
+# Distinct backend code (ELVA-200) meaning the refresh token predates the
+# current format and the user must sign in again - purely informational here,
+# since every 401/403 already routes to a re-login.
+_LEGACY_REFRESH_CODE = "REFRESH_TOKEN_LEGACY"
+
 
 class RefreshFailedError(Exception):
     """The backend positively rejected this refresh token (401/403) — the
@@ -151,26 +163,70 @@ def _refresh_lock() -> Iterator[None]:
             os.close(fd)
 
 
-def _refresh(refresh_token: str, *, base_url: str, timeout: float = _HTTP_TIMEOUT) -> Credentials:
+def _refresh(
+    refresh_token: str,
+    *,
+    base_url: str,
+    timeout: float = _HTTP_TIMEOUT,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Credentials:
+    """Spend the refresh token for a fresh pair.
+
+    Sends X-Elva-Client: cli so the backend answers on the body path and, once
+    its compat flag is off, doesn't reject us as an unmarked client. A 401/403
+    is terminal (RefreshFailedError -> re-login); 429/5xx and network failures
+    are transient and retried with backoff before surfacing as ApiError."""
     import urllib.error
     import urllib.request
 
-    request = urllib.request.Request(
-        f"{base_url}/api/auth/refresh-tokens",
-        data=json.dumps({"refreshToken": refresh_token}).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
+    last_transient: Exception | None = None
+    # Initial attempt (delay 0), then one retry per backoff delay.
+    for delay in (0.0, *_REFRESH_BACKOFF_SECONDS):
+        if delay:
+            sleep(delay)
+        request = urllib.request.Request(
+            f"{base_url}/api/auth/refresh-tokens",
+            data=json.dumps({"refreshToken": refresh_token}).encode("utf-8"),
+            headers={"Content-Type": "application/json", **client_headers()},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 403):
+                # Terminal: the token is dead (expired, rotated away, revoked,
+                # or legacy). Note the backend code when it says so, then
+                # re-login. Not retried.
+                code = _error_code(exc)
+                detail = " (legacy token)" if code == _LEGACY_REFRESH_CODE else ""
+                raise RefreshFailedError(
+                    f"backend rejected refresh token (HTTP {exc.code}){detail}"
+                ) from exc
+            if exc.code == 429 or exc.code >= 500:
+                last_transient = exc
+                continue  # transient - back off and retry
+            raise ApiError(f"Refreshing your session failed (HTTP {exc.code}).") from exc
+        except (urllib.error.URLError, TimeoutError) as exc:
+            last_transient = exc
+            continue  # transient - back off and retry
+        else:
+            return _parse_refresh_body(raw)
+
+    raise ApiError("Could not reach the server to refresh your session.") from last_transient
+
+
+def _error_code(exc: Any) -> str | None:
+    """The backend's machine-readable error code (`data`), if it sent one."""
     try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            raw = response.read()
-    except urllib.error.HTTPError as exc:
-        if exc.code in (401, 403):
-            raise RefreshFailedError(f"backend rejected refresh token (HTTP {exc.code})") from exc
-        raise ApiError(f"Refreshing your session failed (HTTP {exc.code}).") from exc
-    except (urllib.error.URLError, TimeoutError) as exc:
-        raise ApiError("Could not reach the server to refresh your session.") from exc
+        payload = json.loads(exc.read())
+    except (OSError, ValueError):
+        return None
+    code = payload.get("data") if isinstance(payload, dict) else None
+    return code if isinstance(code, str) else None
 
+
+def _parse_refresh_body(raw: bytes) -> Credentials:
     unexpected = "The server returned an unexpected response while refreshing your session."
     try:
         body = json.loads(raw)
@@ -259,6 +315,43 @@ def _refresh_session(*, base_url: str) -> str:
         return refreshed.access_token
 
 
+def refresh_now(*, base_url: str, stale_access_token: str) -> str:
+    """Force a refresh after a request 401'd on a token that looked valid by
+    expiry (the server rejected it early - password change, inactivity, etc.).
+
+    Bounded to sessions. Under the cross-process lock we re-read the store: if
+    another process already rotated (the stored access token differs from the
+    one that 401'd), return that instead of spending a second refresh - the
+    double-spend is exactly what would trip the backend's reuse detection.
+    Raises AuthError if there's no usable session to refresh."""
+    with _refresh_lock():
+        creds, _ = _load_from_first_available_store()
+        if (
+            creds is None
+            or creds.kind != "session"
+            or creds.refresh_token is None
+            or creds.refresh_expires_at is None
+        ):
+            raise AuthError("Your session has expired.")
+
+        if creds.access_token != stale_access_token:
+            # A sibling process refreshed while we held the stale token.
+            return creds.access_token
+
+        if creds.refresh_expires_at <= datetime.now(UTC):
+            _clear_all_stores()
+            raise AuthError("Your session has expired.")
+
+        try:
+            refreshed = _refresh(creds.refresh_token, base_url=base_url)
+        except RefreshFailedError as exc:
+            _clear_all_stores()
+            raise AuthError("Your session has expired.") from exc
+
+        _persist_refreshed(refreshed)
+        return refreshed.access_token
+
+
 def current_identity() -> str:
     """Where get_access_token(base_url=...) would source its token right now:
     'env' (ELVA_TOKEN), 'pat' (a stored personal access token), 'session' (a
@@ -299,7 +392,7 @@ def _revoke_server_side(
     request = urllib.request.Request(
         f"{base_url}/api/auth/logout",
         data=b"",
-        headers={"Authorization": f"Bearer {access_token}"},
+        headers={"Authorization": f"Bearer {access_token}", **client_headers()},
         method="POST",
     )
     try:

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/core/api/http.py

@@ -13,11 +13,17 @@ from __future__ import annotations
 import json
 from typing import TYPE_CHECKING, Any
 
+from elva_cli.core.api.identity import client_headers
 from elva_cli.errors import ApiError, AuthError, ElvaError
 
 if TYPE_CHECKING:
     import urllib.error
-    from collections.abc import Mapping
+    from collections.abc import Callable, Mapping
+
+# Only these methods are safe to auto-retry after a refresh: they're idempotent
+# and carry no body the server may have already acted on. A POST/PATCH that
+# reached the server must not be silently replayed (ELVA-200 CLI review).
+_RETRIABLE_METHODS = frozenset({"GET", "HEAD"})
 
 DEFAULT_TIMEOUT = 30.0
 UNEXPECTED_RESPONSE = "The server returned an unexpected response."
@@ -41,8 +47,14 @@ def default_error(error: HttpError, *, action: str) -> ElvaError:
     return ApiError(f"{action} failed (HTTP {error.status}).")
 
 
-def get_json(url: str, *, token: str, timeout: float = DEFAULT_TIMEOUT) -> Any:
-    return _send(url, token=token, method="GET", timeout=timeout)
+def get_json(
+    url: str,
+    *,
+    token: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    reauth: Callable[[str], str] | None = None,
+) -> Any:
+    return _send(url, token=token, method="GET", timeout=timeout, reauth=reauth)
 
 
 def send_json(
@@ -52,6 +64,7 @@ def send_json(
     method: str,
     payload: Mapping[str, Any],
     timeout: float = DEFAULT_TIMEOUT,
+    reauth: Callable[[str], str] | None = None,
 ) -> Any:
     return _send(
         url,
@@ -60,6 +73,7 @@ def send_json(
         body=json.dumps(payload).encode("utf-8"),
         content_type="application/json",
         timeout=timeout,
+        reauth=reauth,
     )
 
 
@@ -167,11 +181,38 @@ def _send(
     body: bytes | None = None,
     content_type: str | None = None,
     timeout: float,
+    reauth: Callable[[str], str] | None = None,
+) -> Any:
+    try:
+        return _attempt(
+            url, token=token, method=method, body=body, content_type=content_type, timeout=timeout
+        )
+    except HttpError as exc:
+        # A 401 on a token that looked valid means the server rejected it
+        # (e.g. it expired mid-command, or a sibling process rotated it).
+        # Refresh once and retry - but only for idempotent methods, so a
+        # POST/PATCH that already reached the server is never replayed.
+        if exc.status != 401 or reauth is None or method.upper() not in _RETRIABLE_METHODS:
+            raise
+        fresh = reauth(token)
+        return _attempt(
+            url, token=fresh, method=method, body=body, content_type=content_type, timeout=timeout
+        )
+
+
+def _attempt(
+    url: str,
+    *,
+    token: str,
+    method: str,
+    body: bytes | None,
+    content_type: str | None,
+    timeout: float,
 ) -> Any:
     import urllib.error
     import urllib.request
 
-    headers = {"Authorization": f"Bearer {token}"}
+    headers = {"Authorization": f"Bearer {token}", **client_headers()}
     if content_type is not None:
         headers["Content-Type"] = content_type
 

elva_cli-0.5.0/src/elva_cli/core/api/identity.py

@@ -0,0 +1,21 @@
+"""How the CLI identifies itself to the Elva backend.
+
+The `X-Elva-Client: cli` marker tells the refresh endpoint this is a
+non-browser client that takes its refresh token in the response body (ELVA-200).
+While the backend's AUTH_ALLOW_BODY_REFRESH_TOKEN flag is on it also accepts
+unmarked body tokens; once that flag is flipped off (this CLI version being the
+floor), the marker is required and unmarked/legacy tokens are rejected 401.
+"""
+
+from __future__ import annotations
+
+from elva_cli import __version__
+
+CLIENT_HEADER = "X-Elva-Client"
+CLIENT_NAME = "cli"
+USER_AGENT = f"elva-cli/{__version__}"
+
+
+def client_headers() -> dict[str, str]:
+    """Headers every Elva request should carry to identify this client."""
+    return {CLIENT_HEADER: CLIENT_NAME, "User-Agent": USER_AGENT}

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/core/api/targets.py

@@ -10,11 +10,14 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from elva_cli.core.api.http import HttpError, default_error, get_json
 from elva_cli.errors import ApiError, UsageError
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 _OBJECT_ID = re.compile(r"^[0-9a-fA-F]{24}$")
 
 
@@ -24,7 +27,13 @@ class Target:
     name: str
 
 
-def resolve_workspace(*, base_url: str, token: str, workspace: str | None) -> Target:
+def resolve_workspace(
+    *,
+    base_url: str,
+    token: str,
+    workspace: str | None,
+    reauth: Callable[[str], str] | None = None,
+) -> Target:
     """The workspace to act in.
 
     With nothing given, a single-workspace account resolves to that one -- the
@@ -35,7 +44,7 @@ def resolve_workspace(*, base_url: str, token: str, workspace: str | None) -> Ta
         return Target(id=workspace, name=workspace)
 
     try:
-        payload = get_json(f"{base_url}/api/companies/workspaces", token=token)
+        payload = get_json(f"{base_url}/api/companies/workspaces", token=token, reauth=reauth)
     except HttpError as exc:
         raise default_error(exc, action="Looking up your workspaces") from exc
 
@@ -73,13 +82,22 @@ def resolve_workspace(*, base_url: str, token: str, workspace: str | None) -> Ta
     return _exactly_one(matches, kind="workspace", wanted=workspace, available=found)
 
 
-def resolve_collection(*, base_url: str, token: str, company_id: str, collection: str) -> Target:
+def resolve_collection(
+    *,
+    base_url: str,
+    token: str,
+    company_id: str,
+    collection: str,
+    reauth: Callable[[str], str] | None = None,
+) -> Target:
     """The collection to act on, by name or by id."""
     if _OBJECT_ID.match(collection):
         return Target(id=collection, name=collection)
 
     try:
-        payload = get_json(f"{base_url}/api/companies/{company_id}/collections", token=token)
+        payload = get_json(
+            f"{base_url}/api/companies/{company_id}/collections", token=token, reauth=reauth
+        )
     except HttpError as exc:
         if exc.status == 404:
             raise UsageError(

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/core/services/auth.py

@@ -20,6 +20,7 @@ from typing import TYPE_CHECKING, Any
 from elva_cli.auth import logout as logout_credentials
 from elva_cli.auth import save_login
 from elva_cli.auth.store import StoreUnavailableError
+from elva_cli.core.api.identity import client_headers
 from elva_cli.core.services.auth_result import LoginResult, LogoutResult
 from elva_cli.errors import ApiError, AuthError
 
@@ -174,7 +175,7 @@ def _exchange_token(base_url: str, code: str, verifier: str) -> dict[str, Any]:
     request = urllib.request.Request(
         f"{base_url}/api/auth/cli/token",
         data=json.dumps({"code": code, "code_verifier": verifier}).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
+        headers={"Content-Type": "application/json", **client_headers()},
         method="POST",
     )
     try:

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/core/services/import_spec.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from elva_cli.auth import get_access_token
+from elva_cli.auth import get_access_token, refresh_now
 from elva_cli.core.api.http import HttpError, default_error, get_json, send_form, send_json
 from elva_cli.core.api.targets import Target, resolve_collection, resolve_workspace
 from elva_cli.core.services.import_result import Action, DryRunResult, ImportSpecResult
@@ -74,7 +74,13 @@ def import_spec(
         )
 
     token = get_access_token(base_url=base_url)
-    space = resolve_workspace(base_url=base_url, token=token, workspace=workspace)
+
+    # Idempotent lookups/polls refresh-and-retry once on a 401 (e.g. the token
+    # expiring during a large upload); the upload itself is never auto-replayed.
+    def reauth(stale: str) -> str:
+        return refresh_now(base_url=base_url, stale_access_token=stale)
+
+    space = resolve_workspace(base_url=base_url, token=token, workspace=workspace, reauth=reauth)
 
     if update:
         outcome = _update(
@@ -85,6 +91,7 @@ def import_spec(
             source=source,
             data=data,
             spec_url=spec_url,
+            reauth=reauth,
         )
     else:
         outcome = _create(
@@ -306,9 +313,14 @@ def _update(
     source: str,
     data: bytes | None,
     spec_url: str | None,
+    reauth: Callable[[str], str] | None = None,
 ) -> _Outcome:
     target = resolve_collection(
-        base_url=base_url, token=token, company_id=company_id, collection=collection
+        base_url=base_url,
+        token=token,
+        company_id=company_id,
+        collection=collection,
+        reauth=reauth,
     )
     url = f"{base_url}/api/companies/{company_id}/collections/{target.id}"
     try:
@@ -342,6 +354,7 @@ def _update(
         token=token,
         company_id=company_id,
         collection_id=target.id,
+        reauth=reauth,
     )
     return _Outcome(target, doc, confirmed, mcps)
 
@@ -426,6 +439,7 @@ def _settled(
     token: str,
     company_id: str,
     collection_id: str,
+    reauth: Callable[[str], str] | None = None,
 ) -> tuple[dict[str, Any], bool, tuple[str, ...]]:
     """The collection once the server has caught up with the spec just sent,
     whether it was actually observed to catch up, and the MCP servers
@@ -448,7 +462,7 @@ def _settled(
     for delay in _SETTLE_DELAYS:
         time.sleep(delay)
         try:
-            body = get_json(url, token=token)
+            body = get_json(url, token=token, reauth=reauth)
         except (ApiError, HttpError):
             return latest, False, mcps
         doc = _document(body)

{elva_cli-0.4.0 → elva_cli-0.5.0}/src/elva_cli/core/services/whoami.py

@@ -7,11 +7,11 @@ something to optimize away.
 
 from __future__ import annotations
 
-import json
 from typing import Any
 
 from elva_cli import auth
 from elva_cli.auth import get_access_token
+from elva_cli.core.api.http import HttpError, get_json
 from elva_cli.core.services.whoami_result import WhoamiResult
 from elva_cli.errors import ApiError, AuthError
 
@@ -53,28 +53,20 @@ def _rejected_token_error() -> AuthError:
 
 
 def _fetch_me(base_url: str, token: str) -> dict[str, Any]:
-    import urllib.error
-    import urllib.request
+    # GET is idempotent, so on a 401 the shared layer refreshes once and retries
+    # (and carries the X-Elva-Client marker). A refresh that itself fails raises
+    # AuthError/ApiError straight out, which whoami() handles.
+    def reauth(stale: str) -> str:
+        return auth.refresh_now(base_url=base_url, stale_access_token=stale)
 
-    request = urllib.request.Request(
-        f"{base_url}/api/auth/me",
-        headers={"Authorization": f"Bearer {token}"},
-        method="GET",
-    )
+    url = f"{base_url}/api/auth/me"
     try:
-        with urllib.request.urlopen(request, timeout=_HTTP_TIMEOUT) as response:
-            raw = response.read()
-    except urllib.error.HTTPError as exc:
-        if exc.code == 401:
+        body = get_json(url, token=token, timeout=_HTTP_TIMEOUT, reauth=reauth)
+    except HttpError as exc:
+        if exc.status == 401:
             raise AuthError("Your credentials are no longer valid.") from exc
-        raise ApiError(f"Could not verify who you are (HTTP {exc.code}).") from exc
-    except (urllib.error.URLError, TimeoutError) as exc:
-        raise ApiError("Could not reach the server.") from exc
+        raise ApiError(f"Could not verify who you are (HTTP {exc.status}).") from exc
 
-    try:
-        body = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise ApiError(_UNEXPECTED_RESPONSE) from exc
     if not isinstance(body, dict) or "user" not in body:
         raise ApiError(_UNEXPECTED_RESPONSE)
     return body

elva_cli-0.5.0/tests/unit/test_refresh_client.py

@@ -0,0 +1,273 @@
+"""ELVA-200: the CLI as a first-class refresh client.
+
+Covers the X-Elva-Client marker, proactive + forced refresh, the shared HTTP
+layer's 401->refresh->retry (GET/HEAD only), transient backoff, the legacy
+re-login mapping, and crash-safe token persistence.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import urllib.error
+from datetime import UTC, datetime, timedelta
+from email.message import Message
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from elva_cli.auth import session
+from elva_cli.auth.models import Credentials
+from elva_cli.auth.session import RefreshFailedError
+from elva_cli.core.api import http
+from elva_cli.core.api.identity import CLIENT_HEADER
+from elva_cli.errors import ApiError, AuthError, ExitCode
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+BASE_URL = "https://api.getelva.ai"
+
+
+def _tokens_body(access: str = "new-access", refresh: str = "new-refresh") -> bytes:
+    later = "2099-01-01T00:00:00Z"
+    return json.dumps(
+        {
+            "access": {"token": access, "expires": later},
+            "refresh": {"token": refresh, "expires": later},
+        }
+    ).encode()
+
+
+class _Resp:
+    def __init__(self, raw: bytes) -> None:
+        self._raw = raw
+
+    def read(self) -> bytes:
+        return self._raw
+
+    def __enter__(self) -> _Resp:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        return None
+
+
+def _http_error(status: int, body: bytes = b"") -> urllib.error.HTTPError:
+    return urllib.error.HTTPError(
+        f"{BASE_URL}/api/auth/refresh-tokens", status, "err", Message(), io.BytesIO(body)
+    )
+
+
+class TestClientMarker:
+    def test_refresh_sends_the_cli_marker(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        captured: dict[str, Any] = {}
+
+        def fake_urlopen(request: Any, *_a: object, **_k: object) -> _Resp:
+            captured["request"] = request
+            return _Resp(_tokens_body())
+
+        monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+        session._refresh("refresh-1", base_url=BASE_URL)
+
+        request = captured["request"]
+        assert request.get_header(CLIENT_HEADER.capitalize()) == "cli"
+        assert request.get_header("User-agent", "").startswith("elva-cli/")
+
+    def test_every_shared_http_request_carries_the_marker(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        captured: dict[str, Any] = {}
+
+        class _Opener:
+            def open(self, request: Any, timeout: float | None = None) -> _Resp:
+                captured["request"] = request
+                return _Resp(b'{"ok": true}')
+
+        monkeypatch.setattr(http, "_opener", lambda: _Opener())
+        http.get_json(f"{BASE_URL}/api/auth/me", token="tok")
+
+        assert captured["request"].get_header(CLIENT_HEADER.capitalize()) == "cli"
+
+
+class TestRefreshResilience:
+    def test_429_then_success_backs_off_and_recovers(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        calls = {"n": 0}
+
+        def fake_urlopen(*_a: object, **_k: object) -> _Resp:
+            calls["n"] += 1
+            if calls["n"] < 3:
+                raise _http_error(429)
+            return _Resp(_tokens_body(access="recovered"))
+
+        slept: list[float] = []
+        monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+        creds = session._refresh("refresh-1", base_url=BASE_URL, sleep=slept.append)
+
+        assert creds.access_token == "recovered"
+        assert calls["n"] == 3
+        assert slept == [1.0, 2.0]  # backed off before the two retries
+
+    def test_persistent_5xx_gives_up_as_a_transient_api_error(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        def always_503(*_a: object, **_k: object) -> None:
+            raise _http_error(503)
+
+        monkeypatch.setattr("urllib.request.urlopen", always_503)
+        with pytest.raises(ApiError):
+            session._refresh("refresh-1", base_url=BASE_URL, sleep=lambda _s: None)
+
+    def test_legacy_token_is_a_terminal_refresh_failure(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        body = json.dumps({"code": 401, "data": "REFRESH_TOKEN_LEGACY"}).encode()
+
+        def legacy_401(*_a: object, **_k: object) -> None:
+            raise _http_error(401, body)
+
+        monkeypatch.setattr("urllib.request.urlopen", legacy_401)
+        with pytest.raises(RefreshFailedError) as caught:
+            session._refresh("refresh-1", base_url=BASE_URL)
+        assert "legacy" in str(caught.value)
+
+    def test_a_dead_session_maps_to_auth_error_exit_3(self) -> None:
+        # A RefreshFailedError becomes AuthError, whose exit code is AUTH (3),
+        # with the "run elva auth login" hint.
+        err = AuthError("Your session has expired.")
+        assert err.exit_code == ExitCode.AUTH
+        assert err.hint is not None and "elva auth login" in err.hint
+
+
+class TestRefreshNow:
+    @staticmethod
+    def _install(monkeypatch: pytest.MonkeyPatch, creds: Credentials) -> None:
+        monkeypatch.setattr(session, "_load_from_first_available_store", lambda: (creds, object()))
+
+    def test_returns_a_siblings_token_without_spending_a_refresh(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: tmp_path)
+        now = datetime.now(UTC)
+        stored = Credentials(
+            kind="session",
+            access_token="already-rotated-by-sibling",
+            access_expires_at=now + timedelta(minutes=10),
+            refresh_token="refresh-2",
+            refresh_expires_at=now + timedelta(days=1),
+        )
+        self._install(monkeypatch, stored)
+
+        def forbidden(*_a: object, **_k: object) -> Credentials:
+            raise AssertionError("must not spend a refresh when a sibling already rotated")
+
+        monkeypatch.setattr(session, "_refresh", forbidden)
+
+        token = session.refresh_now(base_url=BASE_URL, stale_access_token="the-stale-one")
+        assert token == "already-rotated-by-sibling"
+
+    def test_forces_a_refresh_when_the_stale_token_is_still_current(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: tmp_path)
+        now = datetime.now(UTC)
+        stored = Credentials(
+            kind="session",
+            access_token="stale",
+            # Not near expiry, so the ordinary near-expiry path wouldn't refresh;
+            # a 401 forces it anyway.
+            access_expires_at=now + timedelta(minutes=10),
+            refresh_token="refresh-3",
+            refresh_expires_at=now + timedelta(days=1),
+        )
+        self._install(monkeypatch, stored)
+        monkeypatch.setattr(session, "_persist_refreshed", lambda _c: None)
+        monkeypatch.setattr(
+            session,
+            "_refresh",
+            lambda token, *, base_url: Credentials(
+                kind="session",
+                access_token="forced-new",
+                access_expires_at=now + timedelta(minutes=15),
+                refresh_token="refresh-4",
+                refresh_expires_at=now + timedelta(days=1),
+            ),
+        )
+        assert session.refresh_now(base_url=BASE_URL, stale_access_token="stale") == "forced-new"
+
+
+class TestHttpRetry:
+    @staticmethod
+    def _opener(monkeypatch: pytest.MonkeyPatch, sequence: list[Any]) -> dict[str, list[str]]:
+        seen: dict[str, list[str]] = {"tokens": []}
+
+        class _Opener:
+            def open(self, request: Any, timeout: float | None = None) -> _Resp:
+                seen["tokens"].append(request.get_header("Authorization"))
+                outcome = sequence.pop(0)
+                if isinstance(outcome, Exception):
+                    raise outcome
+                return _Resp(outcome)
+
+        monkeypatch.setattr(http, "_opener", lambda: _Opener())
+        return seen
+
+    def test_get_refreshes_and_retries_once_on_401(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        seen = self._opener(
+            monkeypatch,
+            [_http_error(401), b'{"ok": true}'],  # first 401, retry succeeds
+        )
+        refreshed: list[str] = []
+
+        def reauth(stale: str) -> str:
+            refreshed.append(stale)
+            return "fresh-token"
+
+        body = http.get_json(f"{BASE_URL}/api/auth/me", token="stale-token", reauth=reauth)
+
+        assert body == {"ok": True}
+        assert refreshed == ["stale-token"]  # reauth was handed the stale token
+        assert seen["tokens"] == ["Bearer stale-token", "Bearer fresh-token"]
+
+    def test_post_is_not_retried_after_401(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        self._opener(monkeypatch, [_http_error(401)])
+        called = {"reauth": False}
+
+        def reauth(_stale: str) -> str:
+            called["reauth"] = True
+            return "fresh"
+
+        with pytest.raises(http.HttpError):
+            http.send_json(
+                f"{BASE_URL}/api/x", token="tok", method="POST", payload={}, reauth=reauth
+            )
+        assert called["reauth"] is False  # non-idempotent: never auto-replayed
+
+
+class TestCrashSafePersist:
+    def test_a_failed_write_leaves_the_old_credentials_intact(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        monkeypatch.setattr("elva_cli.settings.paths.config_dir", lambda: tmp_path)
+        from elva_cli.auth.store import FileStore
+
+        store = FileStore()
+        old = Credentials.from_pat("old-token")
+        store.save(old)
+
+        # Simulate a crash after the temp file is written but before the rename.
+        import pathlib
+
+        def boom(self: pathlib.Path, target: Any) -> None:
+            raise OSError("crash before rename")
+
+        monkeypatch.setattr(pathlib.Path, "replace", boom)
+
+        new = Credentials.from_pat("new-token")
+        with pytest.raises(OSError, match="crash before rename"):
+            store.save(new)
+
+        # The old file is still there and readable; no partial/temp file leaks.
+        assert store.load() == old
+        leftovers = list(tmp_path.glob("credentials.json.*.tmp"))
+        assert leftovers == []

{elva_cli-0.4.0 → elva_cli-0.5.0}/tests/unit/test_targets.py

@@ -16,7 +16,7 @@ def responder(monkeypatch: pytest.MonkeyPatch, payload: Any) -> list[str]:
     """Replace the GET and record which URLs were asked for."""
     seen: list[str] = []
 
-    def fake_get(url: str, *, token: str, timeout: float = 30.0) -> Any:
+    def fake_get(url: str, *, token: str, timeout: float = 30.0, reauth: Any = None) -> Any:
         seen.append(url)
         if isinstance(payload, Exception):
             raise payload

{elva_cli-0.4.0 → elva_cli-0.5.0}/tests/unit/test_whoami_flow.py

@@ -1,10 +1,9 @@
 from __future__ import annotations
 
-from urllib.error import HTTPError, URLError
-
 import pytest
 from rich.text import Text
 
+from elva_cli.core.api.http import HttpError
 from elva_cli.core.services import whoami as whoami_service
 from elva_cli.core.services.whoami_result import WhoamiResult
 from elva_cli.errors import ApiError, AuthError
@@ -142,25 +141,26 @@ class TestRendering:
 
 class TestFetchMe:
     def test_401_is_an_auth_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        def fake_urlopen(*_args: object, **_kwargs: object) -> None:
-            raise HTTPError(BASE_URL, 401, "unauthorized", None, None)  # type: ignore[arg-type]
+        # A 401 that survives the shared layer's refresh-and-retry.
+        def fake_get(*_a: object, **_k: object) -> None:
+            raise HttpError(401, None)
 
-        monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+        monkeypatch.setattr(whoami_service, "get_json", fake_get)
         with pytest.raises(AuthError):
             whoami_service._fetch_me(BASE_URL, "tok")
 
     def test_other_http_error_is_an_api_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        def fake_urlopen(*_args: object, **_kwargs: object) -> None:
-            raise HTTPError(BASE_URL, 500, "boom", None, None)  # type: ignore[arg-type]
+        def fake_get(*_a: object, **_k: object) -> None:
+            raise HttpError(500, "boom")
 
-        monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+        monkeypatch.setattr(whoami_service, "get_json", fake_get)
         with pytest.raises(ApiError):
             whoami_service._fetch_me(BASE_URL, "tok")
 
     def test_unreachable_server_is_an_api_error(self, monkeypatch: pytest.MonkeyPatch) -> None:
-        def fake_urlopen(*_args: object, **_kwargs: object) -> None:
-            raise URLError("no route to host")
+        def fake_get(*_a: object, **_k: object) -> None:
+            raise ApiError("Could not reach the server.")
 
-        monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+        monkeypatch.setattr(whoami_service, "get_json", fake_get)
         with pytest.raises(ApiError):
             whoami_service._fetch_me(BASE_URL, "tok")