elva-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{elva_cli-0.2.0 → elva_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: elva-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Elva - CLI for Theneo Elva
 Project-URL: Homepage, https://getelva.ai
 Project-URL: Source, https://github.com/Theneo-Inc/theneo-elva-cli
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: keyring>=25
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: pydantic>=2.7
 Requires-Dist: typer<1.0,>=0.15

{elva_cli-0.2.0 → elva_cli-0.3.0}/pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
   "typer>=0.15,<1.0",
   "platformdirs>=4.2",
   "pydantic>=2.7",
+  "keyring>=25",
 ]
 
 [project.optional-dependencies]

{elva_cli-0.2.0 → elva_cli-0.3.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.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

elva_cli-0.3.0/src/elva_cli/auth/__init__.py

@@ -0,0 +1,32 @@
+"""Credentials and the login flow.
+
+Token storage sits behind a Protocol (keyring, with a 0600 file fallback for
+headless Linux and containers). ELVA_TOKEN overrides both in CI. A session's
+access token refreshes itself transparently on a near-expiry read; a dead
+session raises AuthError (exit code 3).
+
+The browser handoff needs a /auth/cli endpoint on the JWT side of the
+backend. The cookie-session auth used by the catalog and GitHub routes is
+deliberately out of scope: a CLI has no cookie jar.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from elva_cli.auth.models import Credentials
+
+if TYPE_CHECKING:
+    from elva_cli.auth.session import ENV_TOKEN, get_access_token, logout, save_login, save_pat
+
+__all__ = ["ENV_TOKEN", "Credentials", "get_access_token", "logout", "save_login", "save_pat"]
+
+_LAZY = frozenset(__all__) - {"Credentials"}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY:
+        from elva_cli.auth import session
+
+        return getattr(session, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

elva_cli-0.3.0/src/elva_cli/auth/models.py

@@ -0,0 +1,100 @@
+"""The Credentials shape: what gets stored, and how it maps to the wire."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+TokenKind = Literal["session", "pat"]
+
+
+def _parse_expiry(value: str) -> datetime:
+    """Parse an ISO-8601 timestamp, forcing it timezone-aware.
+
+    The backend sends UTC with a `Z`, but a hand-edited credentials.json can
+    drop the offset. A naive datetime would later crash get_access_token's
+    `expires - datetime.now(UTC)` arithmetic, so assume UTC when none is
+    given."""
+    parsed = datetime.fromisoformat(value)
+    return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """One stored credential: either an OAuth session (JWT pair, refreshable)
+    or a Personal Access Token (opaque, long-lived, no refresh side)."""
+
+    kind: TokenKind
+    access_token: str
+    access_expires_at: datetime | None
+    refresh_token: str | None
+    refresh_expires_at: datetime | None
+
+    @classmethod
+    def from_auth_tokens(cls, tokens: dict[str, Any]) -> Credentials:
+        """Build a session credential from the backend's AuthTokens shape:
+        {"access": {"token", "expires"}, "refresh": {"token", "expires"}}.
+
+        POST /api/auth/refresh-tokens returns this shape at the top level.
+        The CLI login exchange (POST /api/auth/cli/token) nests it under a
+        "tokens" key alongside "user" — callers there go through
+        `session.save_login`, which unwraps it first."""
+        access = tokens["access"]
+        refresh = tokens["refresh"]
+        return cls(
+            kind="session",
+            access_token=access["token"],
+            access_expires_at=_parse_expiry(access["expires"]),
+            refresh_token=refresh["token"],
+            refresh_expires_at=_parse_expiry(refresh["expires"]),
+        )
+
+    @classmethod
+    def from_pat(cls, token: str) -> Credentials:
+        return cls(
+            kind="pat",
+            access_token=token,
+            access_expires_at=None,
+            refresh_token=None,
+            refresh_expires_at=None,
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "access_token": self.access_token,
+            "access_expires_at": (
+                self.access_expires_at.isoformat() if self.access_expires_at else None
+            ),
+            "refresh_token": self.refresh_token,
+            "refresh_expires_at": (
+                self.refresh_expires_at.isoformat() if self.refresh_expires_at else None
+            ),
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Credentials:
+        kind = data["kind"]
+        if kind not in ("session", "pat"):
+            raise ValueError(f"unknown credential kind: {kind!r}")
+        creds = cls(
+            kind=kind,
+            access_token=data["access_token"],
+            access_expires_at=(
+                _parse_expiry(data["access_expires_at"]) if data.get("access_expires_at") else None
+            ),
+            refresh_token=data.get("refresh_token"),
+            refresh_expires_at=(
+                _parse_expiry(data["refresh_expires_at"])
+                if data.get("refresh_expires_at")
+                else None
+            ),
+        )
+        if creds.kind == "session" and (
+            creds.access_expires_at is None
+            or creds.refresh_token is None
+            or creds.refresh_expires_at is None
+        ):
+            raise ValueError("incomplete session credential")
+        return creds

elva_cli-0.3.0/src/elva_cli/auth/session.py

@@ -0,0 +1,343 @@
+"""Precedence between credential sources, and transparent session refresh.
+
+Order: ELVA_TOKEN env var, then whichever TokenStore (keyring, then file)
+has something. A session's access token refreshes itself silently on a
+near-expiry read; a PAT is used as-is (no expiry the client knows about).
+A refresh token that's also expired, or a refresh the backend positively
+rejects (401/403), surfaces as AuthError — exit code 3, "Run 'elva auth
+login' to sign in." A transient refresh failure (network down, timeout,
+5xx) surfaces as ApiError and leaves stored credentials intact.
+
+The refresh itself is serialised across concurrent `elva` processes with a
+file lock (see _refresh_lock): the backend spends a refresh token on first
+use, so two processes racing to refresh the same near-expiry session would
+have one 401 and, on that 401, clear the credentials the other just saved.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+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.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
+
+_logger = logging.getLogger(__name__)
+
+ENV_TOKEN = "ELVA_TOKEN"
+_SKEW = timedelta(seconds=60)
+_LOCK_FILE = "refresh.lock"
+_HTTP_TIMEOUT = 10
+_LOGOUT_TIMEOUT = 5
+
+
+class RefreshFailedError(Exception):
+    """The backend positively rejected this refresh token (401/403) — the
+    session is dead and its credentials should be cleared.
+
+    A transient failure (network down, timeout, 5xx, a captive-portal error
+    page) is NOT this — it raises ApiError instead and leaves credentials
+    untouched, so a flaky connection can't force a full re-login."""
+
+
+def _stores() -> list[TokenStore]:
+    return [KeyringStore(), FileStore()]
+
+
+def _load_from_first_available_store() -> tuple[Credentials | None, TokenStore | None]:
+    for store in _stores():
+        creds = store.load()
+        if creds is not None:
+            return creds, store
+    return None, None
+
+
+def _clear_all_stores() -> None:
+    for store in _stores():
+        store.clear()
+
+
+def _save_preferring_keyring(creds: Credentials) -> None:
+    """Persist to exactly one store and clear the other, so a stale copy in
+    the store we're *not* using can never shadow this one on the next read
+    (get_access_token checks the keyring first)."""
+    try:
+        KeyringStore().save(creds)
+    except StoreUnavailableError:
+        FileStore().save(creds)
+        KeyringStore().clear()
+    else:
+        FileStore().clear()
+
+
+def _persist_refreshed(creds: Credentials) -> None:
+    """Save a freshly refreshed session.
+
+    The refresh token that produced it is already spent server-side, so if
+    this doesn't land the next run is a forced re-login. Go through
+    _save_preferring_keyring so a single failing store falls back to the
+    other one, and if even that fails, say so instead of failing silently.
+    This module sits below the ui/ boundary (see tests/unit/test_boundary.py)
+    and must not print — logging is the escape hatch for a below-boundary
+    module that still needs to surface something; elva_cli.logging is what
+    wires a handler up to it."""
+    try:
+        _save_preferring_keyring(creds)
+    except (StoreUnavailableError, OSError):
+        _logger.warning(
+            "your session was refreshed but could not be saved; "
+            "you may need to run 'elva auth login' again."
+        )
+
+
+def _acquire_lock_fd() -> int | None:
+    """An fd holding an exclusive advisory lock on the refresh lock file, or
+    None if locking isn't available here (non-POSIX, or a filesystem with no
+    working flock — NFS without lockd, some container overlays). A None means
+    "couldn't serialise"; the caller then just refreshes unlocked, exactly as
+    it did before this lock existed."""
+    try:
+        import fcntl
+    except ImportError:  # non-POSIX
+        return None
+
+    try:
+        directory = paths.config_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        fd = os.open(directory / _LOCK_FILE, os.O_CREAT | os.O_RDWR, 0o600)
+    except OSError:
+        return None
+
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+    except OSError:
+        with contextlib.suppress(OSError):
+            os.close(fd)
+        return None
+    return fd
+
+
+@contextlib.contextmanager
+def _refresh_lock() -> Iterator[None]:
+    """Hold the cross-process refresh lock for the duration of the block.
+
+    Best-effort: if the lock can't be taken the block still runs, just
+    without serialisation. The caller must re-read the store inside the
+    block — by the time a waiter gets in, the process that held the lock has
+    usually already saved a fresh token."""
+    fd = _acquire_lock_fd()
+    if fd is None:
+        yield
+        return
+    try:
+        yield
+    finally:
+        import fcntl
+
+        with contextlib.suppress(OSError):
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        with contextlib.suppress(OSError):
+            os.close(fd)
+
+
+def _refresh(refresh_token: str, *, base_url: str, timeout: float = _HTTP_TIMEOUT) -> Credentials:
+    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",
+    )
+    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
+
+    unexpected = "The server returned an unexpected response while refreshing your session."
+    try:
+        body = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ApiError(unexpected) from exc
+    if not isinstance(body, dict):
+        raise ApiError(unexpected)
+    try:
+        return Credentials.from_auth_tokens(body)
+    except (KeyError, ValueError, TypeError) as exc:
+        raise ApiError(unexpected) from exc
+
+
+def get_access_token(*, base_url: str) -> str:
+    """The bearer token to send on this request. Refreshes a near-expiry
+    session transparently; raises AuthError if there's nothing usable."""
+    env_token = os.environ.get(ENV_TOKEN)
+    if env_token:
+        return env_token
+
+    creds, store = _load_from_first_available_store()
+    if creds is None or store is None:
+        raise AuthError("You're not logged in.")
+
+    if creds.kind == "pat":
+        return creds.access_token
+
+    now = datetime.now(UTC)
+    if (
+        creds.access_expires_at is None
+        or creds.refresh_expires_at is None
+        or creds.refresh_token is None
+    ):
+        raise AuthError("You're not logged in.")
+
+    if creds.access_expires_at - now > _SKEW:
+        return creds.access_token
+
+    if creds.refresh_expires_at <= now:
+        _clear_all_stores()
+        raise AuthError("Your session has expired.")
+
+    return _refresh_session(base_url=base_url)
+
+
+def _refresh_session(*, base_url: str) -> str:
+    """Refresh the stored session under the cross-process lock and return the
+    new access token.
+
+    The store is re-read *inside* the lock: a process that waited for the
+    lock normally finds that the holder already refreshed and saved, and
+    returns that token without a network call. This is what stops a
+    single-use refresh token from being spent twice — the second spend 401s,
+    and the 401 handler would wipe the other process's fresh credentials."""
+    with _refresh_lock():
+        creds, store = _load_from_first_available_store()
+        if (
+            creds is None
+            or store is None
+            or creds.kind != "session"
+            or creds.access_expires_at is None
+            or creds.refresh_expires_at is None
+            or creds.refresh_token is None
+        ):
+            raise AuthError("Your session has expired.")
+
+        now = datetime.now(UTC)
+        if creds.access_expires_at - now > _SKEW:
+            return creds.access_token
+
+        if creds.refresh_expires_at <= now:
+            _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
+        except ApiError:
+            if creds.access_expires_at - datetime.now(UTC) > timedelta(0):
+                return creds.access_token
+            raise
+
+        _persist_refreshed(refreshed)
+        return refreshed.access_token
+
+
+def save_login(payload: dict[str, Any]) -> None:
+    """Persist a fresh OAuth session from the CLI login exchange.
+
+    POST /api/auth/cli/token responds with {"user": ..., "tokens": {...}};
+    the refresh endpoint responds with the bare {"access", "refresh"} shape.
+    Accept either so callers don't have to care which one they hold."""
+    tokens = payload.get("tokens", payload)
+    _save_preferring_keyring(Credentials.from_auth_tokens(tokens))
+
+
+def save_pat(token: str) -> None:
+    """Persist a Personal Access Token."""
+    _save_preferring_keyring(Credentials.from_pat(token))
+
+
+def _revoke_server_side(
+    access_token: str, *, base_url: str, timeout: float = _HTTP_TIMEOUT
+) -> bool:
+    """POST /api/auth/logout."""
+    import urllib.error
+    import urllib.request
+
+    request = urllib.request.Request(
+        f"{base_url}/api/auth/logout",
+        data=b"",
+        headers={"Authorization": f"Bearer {access_token}"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout):
+            pass
+    except (urllib.error.URLError, TimeoutError):
+        return False
+    return True
+
+
+def _revocation_token(
+    creds: Credentials, *, base_url: str, timeout: float = _HTTP_TIMEOUT
+) -> str | None:
+    """An access token that will still authenticate the logout call, or None
+    if the session is already dead server-side and there's nothing to revoke."""
+    now = datetime.now(UTC)
+    if creds.access_expires_at is not None and creds.access_expires_at - now > _SKEW:
+        return creds.access_token
+    if (
+        creds.refresh_token is None
+        or creds.refresh_expires_at is None
+        or creds.refresh_expires_at <= now
+    ):
+        return None
+    try:
+        refreshed = _refresh(creds.refresh_token, base_url=base_url, timeout=timeout)
+    except RefreshFailedError:
+        return None
+    _persist_refreshed(refreshed)
+    return refreshed.access_token
+
+
+def logout(*, base_url: str) -> LogoutResult:
+    """Forget the stored credentials and, best-effort, revoke the session
+    server-side (POST /api/auth/logout)."""
+    with _refresh_lock():
+        creds, _ = _load_from_first_available_store()
+        if creds is None:
+            _clear_all_stores()
+            return LogoutResult(status=LogoutStatus.NOT_SIGNED_IN)
+        if creds.kind == "pat":
+            _clear_all_stores()
+            return LogoutResult(status=LogoutStatus.SIGNED_OUT)
+        try:
+            token = _revocation_token(creds, base_url=base_url, timeout=_LOGOUT_TIMEOUT)
+        except ApiError:
+            return LogoutResult(status=LogoutStatus.REVOCATION_FAILED)
+        if token is None:
+            # Refresh token expired or rejected — the session is already dead
+            _clear_all_stores()
+            return LogoutResult(status=LogoutStatus.SIGNED_OUT)
+        if _revoke_server_side(token, base_url=base_url, timeout=_LOGOUT_TIMEOUT):
+            _clear_all_stores()
+            return LogoutResult(status=LogoutStatus.SIGNED_OUT)
+        # The token was good but the POST didn't land
+        return LogoutResult(status=LogoutStatus.REVOCATION_FAILED)

elva_cli-0.3.0/src/elva_cli/auth/store.py

@@ -0,0 +1,121 @@
+"""Where a Credentials blob actually lives: OS keyring first, a 0600 file
+for machines with no keyring backend (headless Linux, containers).
+
+Deliberately does NOT depend on `keyrings.alt`: without it, `keyring` fails
+over cleanly on a box with no real secret service instead of silently
+writing through its own weakly-obfuscated plaintext backend — so it's
+*this* module's documented file fallback that fires, not a hidden one.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Protocol
+
+from elva_cli.auth.models import Credentials
+from elva_cli.settings import paths
+
+_SERVICE = "elva-cli"
+_USERNAME = "default"
+_CREDENTIALS_FILE = "credentials.json"
+
+
+class StoreUnavailableError(Exception):
+    """This store can't be written to right now (e.g. no keyring backend).
+
+    Internal to auth/ — callers fall through to the next store, never a
+    user-facing error on its own.
+    """
+
+
+class TokenStore(Protocol):
+    def load(self) -> Credentials | None: ...
+    def save(self, creds: Credentials) -> None: ...
+    def clear(self) -> None: ...
+
+
+class KeyringStore:
+    """Backed by the OS keyring (Keychain / libsecret / Credential Manager)."""
+
+    def load(self) -> Credentials | None:
+        import keyring
+
+        try:
+            raw = keyring.get_password(_SERVICE, _USERNAME)
+        except Exception:
+            return None
+        if raw is None:
+            return None
+        try:
+            return Credentials.from_json(json.loads(raw))
+        except (json.JSONDecodeError, KeyError, ValueError, TypeError):
+            return None
+
+    def save(self, creds: Credentials) -> None:
+        import keyring
+
+        try:
+            keyring.set_password(_SERVICE, _USERNAME, json.dumps(creds.to_json()))
+        except Exception as exc:
+            raise StoreUnavailableError(str(exc)) from exc
+
+    def clear(self) -> None:
+        import keyring
+
+        # Already absent, or no backend — either way, nothing to clear.
+        with contextlib.suppress(Exception):
+            keyring.delete_password(_SERVICE, _USERNAME)
+
+
+class FileStore:
+    """0600 JSON file under the CLI's config dir. The documented fallback
+    for headless Linux / containers where no keyring daemon is running."""
+
+    def _path(self) -> Path:
+        return paths.config_dir() / _CREDENTIALS_FILE
+
+    def load(self) -> Credentials | None:
+        path = self._path()
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+        try:
+            return Credentials.from_json(json.loads(raw))
+        except (json.JSONDecodeError, KeyError, ValueError, TypeError):
+            return None
+
+    def save(self, creds: Credentials) -> None:
+        directory = paths.config_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        directory.chmod(0o700)
+
+        path = directory / _CREDENTIALS_FILE
+        payload = json.dumps(creds.to_json()).encode("utf-8")
+
+        fd, tmp_name = tempfile.mkstemp(
+            prefix=f"{_CREDENTIALS_FILE}.", suffix=".tmp", dir=directory
+        )
+        tmp_path = Path(tmp_name)
+        try:
+            try:
+                os.write(fd, payload)
+            finally:
+                os.close(fd)
+            tmp_path.replace(path)  # atomic on POSIX and Windows
+        except BaseException:
+            with contextlib.suppress(OSError):
+                tmp_path.unlink()
+            raise
+
+    def clear(self) -> None:
+        with contextlib.suppress(OSError):
+            self._path().unlink(missing_ok=True)
+        # Also sweep any temp files left by an interrupted save.
+        for leftover in self._path().parent.glob(f"{_CREDENTIALS_FILE}.*.tmp"):
+            with contextlib.suppress(OSError):
+                leftover.unlink()

elva_cli-0.3.0/src/elva_cli/commands/auth.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import typer
+
+from elva_cli.context import get_ctx
+
+app = typer.Typer(name="auth", help="Sign in and manage credentials.", no_args_is_help=True)
+
+
+@app.command("login")
+def login(click_ctx: typer.Context) -> None:
+    """Sign in via your browser."""
+    from elva_cli.core.services.auth import login as login_service
+
+    ctx = get_ctx(click_ctx)
+    result = login_service(
+        base_url=ctx.settings.base_url,
+        on_progress=ctx.out.hint,
+        interactive=ctx.interactive,
+    )
+    ctx.out.result(result)
+
+
+@app.command("logout")
+def logout(click_ctx: typer.Context) -> None:
+    """Sign out and forget your stored credentials."""
+    from elva_cli.auth import ENV_TOKEN
+    from elva_cli.core.services.auth import logout as logout_service
+
+    ctx = get_ctx(click_ctx)
+    result = logout_service(base_url=ctx.settings.base_url)
+    ctx.out.result(result)
+    if ctx.env.get(ENV_TOKEN):
+        ctx.out.warn(
+            f"{ENV_TOKEN} is set and will still be used to authenticate. "
+            "Unset it to fully sign out."
+        )