icmd-python 3.3.4__py3-none-any.whl → 3.3.5__py3-none-any.whl

icmd/apps/agent.py

@@ -212,5 +212,16 @@ class AgentApp:
         return self._client.request_json("get", "agent/providers")
 
     def usage(self) -> dict | list[dict]:
-        """Get the group's monthly Assist token usage (``GET agent/assist/usage``)."""
+        """Get the group's Assist credit balance (``GET agent/assist/usage``).
+
+        Group admins only.
+
+        Returns
+        -------
+        dict
+            ``granted``, ``used``, ``balance`` and ``month_used`` in credits,
+            and ``status`` (``"ok"`` / ``"low"`` / ``"out"``).  ``balance``
+            can be negative.  An unmetered group returns ``None`` for all five
+            keys, ``status`` included.
+        """
         return self._client.request_json("get", "agent/assist/usage")

icmd/cli/__init__.py

@@ -5,6 +5,7 @@ Entry point: ``icmd`` (installed via ``[project.scripts]``).
 
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 import click
@@ -23,7 +24,7 @@ from icmd.version import __version__
 from .account import agent_usage, register_account_commands
 from .auth import CLIAuthenticator
 from .auth_status import auth_cmd
-from .client import _build_account_client
+from .client import _build_account_client, build_client
 from .commands import (
     _domain_option,
     _format,
@@ -139,12 +140,21 @@ def login() -> None:
 @cli.command()
 @_domain_option
 def logout() -> None:
-    """Clear cached credentials for an ICMD® instance."""
+    """Sign out of an ICMD® instance and clear its cached credentials."""
     ctx = click.get_current_context()
-    normalized = normalize_domain(_require_domain(ctx))
-    # Straight to the store, not through ``ICMD.logout``: that path treats a
-    # developer-token client differently on purpose.
-    CredentialManager().clear_domain_credentials(normalized)
+    domain = _require_domain(ctx)
+    normalized = normalize_domain(domain)
+    store = CredentialManager()
+    # Revoke a saved login on the server first, or its refresh token stays
+    # usable until it expires. Gated on a stored refresh token so that with
+    # nothing saved no client is built (no request, no prompt). Best effort:
+    # the local clear runs whatever the server does, Ctrl-C included.
+    try:
+        if store.get_refresh_token(normalized):
+            with contextlib.suppress(Exception):
+                build_client(domain).logout(clear_saved_credentials=True)
+    finally:
+        store.clear_domain_credentials(normalized)
     write_output({"status": "ok", "domain": normalized}, fmt=_format(ctx))
 
 

icmd/cli/account.py

@@ -371,7 +371,10 @@ def invite_cancel(uuid: str, yes: bool) -> None:
 @click.command("usage")
 @_global_options
 def agent_usage() -> None:
-    """Get the group's monthly ICMD® Assist token usage.
+    """Get the group's ICMD® Assist credit balance.
+
+    Prints ``granted`` / ``used`` / ``balance`` / ``month_used`` (credits) and
+    ``status``; ``null`` values mean the group is unmetered.
 
     Unlike the account commands, this is group-scoped: it honours ``--group``
     and injects ``owner_group`` (the backend gates on group-admin membership).

icmd/client.py

@@ -148,11 +148,9 @@ class ICMD:
     def _save_credentials(self) -> None:
         """Persist the credentials produced by an interactive login.
 
-        Only ever called after an interactive flow, and deliberately so: it
-        writes ``self._session.refresh_token``, which a *refresh* has replaced
-        with the server's rotated token.  Persisting a rotation would roll the
-        backend's absolute session cap forward on every refresh, so the refresh
-        path saves the access token alone (:meth:`_cache_access_token`).
+        Only ever called after an interactive flow: it replaces the whole
+        record unconditionally, whereas a refresh must write only while the
+        record still holds the token it presented (:meth:`_cache_access_token`).
         """
         issued = self._session.refresh_token
         self._credentials.save_domain_credentials(
@@ -167,8 +165,9 @@ class ICMD:
     def _cache_access_token(self, refresh_token: str | None = None) -> None:
         """Cache the session's access token for the next process to reuse.
 
-        Writes only the access-token fields — never a refresh token — which is
-        what keeps a rotated token off disk.
+        A refresh token the server rotated in exchange for *refresh_token* is
+        written with it, in the same compare-and-swap, so the next process
+        presents the current token rather than a superseded one.
 
         Parameters
         ----------
@@ -185,11 +184,13 @@ class ICMD:
         """
         if not self._session.has_valid_token():
             return
+        current = self._session.refresh_token
         self._credentials.save_access_token(
             self._session.domain,
             self._session.access_token,
-            expires_at=self._session.access_token_expires_at,
+            expires=self._session.access_token_expires_at,
             expected_refresh_token=refresh_token,
+            rotated_refresh_token=current if current and current != refresh_token else None,
         )
 
     def _adopt_cached_access_token(self) -> bool:
@@ -347,8 +348,11 @@ class ICMD:
         """Clear cached credentials for a domain.
 
         Removes the whole record — refresh token and cached access token
-        alike — unconditionally: this is the explicit sign-out path, not a
-        reaction to a token the server rejected.
+        alike — unconditionally, not as a reaction to a token the server
+        rejected.  Local only: the server session stays live; use
+        :meth:`logout` to end it.  Processes already running on that login
+        may then sign it out, since each rotates its refresh token on its
+        own once the record is gone.
 
         Can be called without an ``ICMD`` instance, which is useful when
         instantiation itself fails (e.g. after a server-side auth-method
@@ -506,10 +510,13 @@ class ICMD:
         Parameters
         ----------
         clear_saved_credentials : bool
-            Also clear the stored refresh token, so the next client
-            authenticates interactively.  The cached access token is dropped
-            either way — it belongs to the session just ended, and leaving it
-            behind would let another process keep using it.
+            Also clear the stored refresh token.  Every refresh token of a
+            login belongs to the session just ended, so once the server has
+            ended it the stored one is dead either way; clearing it only spares
+            the next client one rejected refresh before it authenticates
+            interactively.  The cached access
+            token is dropped either way — it belongs to the session just ended,
+            and leaving it behind would let another process keep using it.
 
         Notes
         -----

icmd/core/credentials.py

@@ -41,7 +41,7 @@ Per-domain record::
 
     {
       "auth_method": "SAML",              # required for auth-method detection
-      "refresh_token": "…",               # long-lived; never rotated on disk
+      "refresh_token": "…",               # long-lived; replaced when a refresh rotates it
       "access_token": "…",                # optional cache, short-lived
       "access_token_expires_at": "…",     # absolute UTC ISO-8601 timestamp
       "saved_at": "…"
@@ -717,18 +717,15 @@ class CredentialManager:
         domain: str,
         access_token: str,
         *,
-        expires_in: float | None = None,
-        expires_at: datetime | None = None,
+        expires: float | datetime | None = None,
         expected_refresh_token: str | None = None,
+        rotated_refresh_token: str | None = None,
     ) -> bool:
-        """Cache an access token for *domain* without touching the refresh token.
+        """Cache an access token for *domain*, with the refresh token rotated beside it.
 
         This is the only writer of the access-token fields, and it merges into
-        the existing record rather than replacing it.  That is deliberate: the
-        stored refresh token must stay exactly as it is on disk, because the
-        server mints a *new* refresh token on every exchange and persisting the
-        rotation would roll the backend's absolute session cap forward
-        indefinitely.
+        the existing record rather than replacing it, so the auth method and
+        the rest of the record survive.
 
         Parameters
         ----------
@@ -736,11 +733,10 @@ class CredentialManager:
             Normalised ICMD domain the token belongs to.
         access_token : str
             The access token to cache.
-        expires_in : float | None
-            Lifetime in seconds as reported by the server, measured from now.
-        expires_at : datetime | None
-            Absolute expiry; wins over *expires_in* when both are given.  A
-            naive value is interpreted as UTC.
+        expires : float | datetime | None
+            A number is the lifetime in seconds as reported by the server,
+            measured from now; a datetime is the absolute expiry, and a naive
+            one is interpreted as UTC.
         expected_refresh_token : str | None
             When given, cache only while the stored refresh token is still
             exactly this value — the compare-and-swap counterpart to
@@ -751,6 +747,12 @@ class CredentialManager:
             would resurrect a signed-out record (an access-token-only leftover
             that the next process happily adopts) or file one account's token
             under another's.  ``None`` merges unconditionally.
+        rotated_refresh_token : str | None
+            The refresh token the server returned with *access_token*, when it
+            differs from the one presented.  Written in the same rewrite, after
+            the *expected_refresh_token* check, so both tokens land or neither
+            does.  A failed write is logged at WARNING: the stored token is then
+            one the server has already superseded.
 
         Returns
         -------
@@ -765,24 +767,26 @@ class CredentialManager:
         Raises
         ------
         ValueError
-            If neither *expires_in* nor *expires_at* is given.
+            If *expires* is not given.
         """
-        if expires_in is None and expires_at is None:
-            raise ValueError("save_access_token requires either expires_in or expires_at")
+        if expires is None:
+            raise ValueError("save_access_token requires expires")
 
         if not access_token or not isinstance(access_token, str):
             logger.debug("Refusing to cache an empty access token for %s", domain)
             return False
 
-        resolved = self._resolve_expiry(expires_in, expires_at)
+        resolved = self._resolve_expiry(expires)
         if resolved is None:
             logger.debug("Access token for %s has no usable expiry; not caching", domain)
             return False
 
         stamp = resolved.isoformat()
         canonical = canonical_domain(domain)
+        attempted = False
 
         def mutate(records: dict[str, Any]) -> bool:
+            nonlocal attempted
             # Folded before the compare-and-swap, so the token compared against
             # is the one this domain's single surviving record holds.  Refusing
             # below writes nothing and discards the fold with it; the next
@@ -804,23 +808,32 @@ class CredentialManager:
                 records[canonical] = record
             record[_ACCESS_TOKEN_KEY] = access_token
             record[_ACCESS_TOKEN_EXPIRES_AT_KEY] = stamp
+            if rotated_refresh_token:
+                record[_REFRESH_TOKEN_KEY] = rotated_refresh_token
+            attempted = True
             return True
 
-        return self._mutate_store(mutate)
+        saved = self._mutate_store(mutate)
+        if attempted and not saved and rotated_refresh_token:
+            logger.warning(
+                "Could not save the rotated refresh token for %s; this process's next "
+                "refresh and any later process will present a superseded one, which "
+                "signs the login out.",
+                domain,
+            )
+        return saved
 
     @staticmethod
-    def _resolve_expiry(expires_in: float | None, expires_at: datetime | None) -> datetime | None:
-        """Resolve the two expiry forms into one absolute UTC timestamp."""
-        if expires_at is not None:
-            if not isinstance(expires_at, datetime):
-                return None
-            return expires_at.replace(tzinfo=UTC) if expires_at.tzinfo is None else expires_at
+    def _resolve_expiry(expires: float | datetime) -> datetime | None:
+        """Resolve either expiry form into one absolute UTC timestamp."""
+        if isinstance(expires, datetime):
+            return expires.replace(tzinfo=UTC) if expires.tzinfo is None else expires
 
-        if not isinstance(expires_in, int | float) or isinstance(expires_in, bool):
+        if not isinstance(expires, int | float) or isinstance(expires, bool):
             return None
-        if expires_in <= 0:
+        if expires <= 0:
             return None
-        return datetime.now(UTC) + timedelta(seconds=float(expires_in))
+        return datetime.now(UTC) + timedelta(seconds=float(expires))
 
     def _mutate_store(self, mutate: Callable[[dict[str, Any]], bool]) -> bool:
         """Read, mutate, and atomically rewrite the store under the credential lock.

icmd/core/session.py

@@ -9,6 +9,7 @@ this module only manages token state.
 
 from __future__ import annotations
 
+import logging
 import os
 import re
 import warnings
@@ -60,6 +61,8 @@ if TYPE_CHECKING:
     from .constants import HTTPMethod
     from .contracts import ContractClient
 
+logger = logging.getLogger(__name__)
+
 
 class ResourceClient(Protocol):
     """Structural type for objects that can make JSON API requests."""
@@ -718,7 +721,6 @@ class Session:
     EXCLUDED_ENDPOINTS: ClassVar[set[str]] = {
         LOGIN,
         AUTH_REFRESH,
-        AUTH_LOGOUT,
         MFA_VERIFY,
         MFA_EMAIL_GENERATE,
         SAML_LOGIN,
@@ -1162,15 +1164,11 @@ class Session:
 
         # The server already refused this exact access token on a 401 that a
         # refresh did not fix, so exchanging again cannot help — and would not
-        # be free: the on-disk refresh token is deliberately never rotated, so
-        # every attempt presents the same one and lands in the same
-        # ``(client IP, sha256(refresh token))`` throttle bucket.  Without this,
-        # a 401 that is not about expiry (an authorization failure, a proxy
-        # stripping ``Authorization``) costs one refresh POST per *request* and
-        # exhausts the bucket after 30 — the same refresh lockout the
-        # empty-token guard above prevents, reached by another door.  No reset
-        # is needed: the guard compares against the token currently held, so
-        # any path that installs a new one clears it.
+        # be free.  Without this, a 401 that is not about expiry (an
+        # authorization failure, a proxy stripping ``Authorization``) costs one
+        # refresh POST per *request*, each counted by the server's refresh
+        # throttle.  No reset is needed: the guard compares against the token
+        # currently held, so any path that installs a new one clears it.
         if self._access_token and self._access_token == self._refresh_rejected_token:
             return response
 
@@ -1325,18 +1323,34 @@ class Session:
     # -----------------------------------------------------------------
 
     def logout(self) -> None:
-        """Logout from the server and clear in-memory tokens.
+        """Revoke the server session and clear in-memory tokens.
 
-        Returns silently — callers decide how to communicate success.
+        The server revokes the session named by the bearer, so the POST takes
+        the same renew-then-send path as any authenticated request, including
+        the single refresh-and-retry on a ``401``.  Best effort: it never
+        raises, and the outcome is logged at DEBUG — callers decide how to
+        communicate success.
         """
         try:
             if self._access_token:
-                self._raw_request(
-                    "POST",
-                    f"{self.api_root}/{AUTH_LOGOUT}/",
-                    timeout=5,
-                )
-        except Exception:
-            pass
+                self._renew_expired_token(AUTH_LOGOUT)
+                if (
+                    self._refresh_coordinator is not None
+                    and self._proactive_renewal
+                    and self.is_token_expired()
+                ):
+                    # Renewal had its chance and failed; the server would only
+                    # answer this token with a 401.
+                    logger.debug("Logout skipped: the access token expired and was not renewed")
+                else:
+                    url = f"{self.api_root}/{AUTH_LOGOUT}/"
+                    response = self._raw_request("POST", url, timeout=5)
+                    if response.status_code == HTTPStatus.UNAUTHORIZED:
+                        response = self._retry_on_unauthorized(
+                            response, AUTH_LOGOUT, "POST", url, timeout=5
+                        )
+                    logger.debug("Logout answered HTTP %s", response.status_code)
+        except Exception as exc:
+            logger.debug("Logout request failed: %s", exc)
 
         self.clear_tokens()

icmd/version.py

@@ -1 +1 @@
-__version__ = "3.3.4"
+__version__ = "3.3.5"

{icmd_python-3.3.4.dist-info → icmd_python-3.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: icmd-python
-Version: 3.3.4
+Version: 3.3.5
 Summary: Python client app for ICMD®
 Author: QuesTek Innovations LLC
 License-Expression: LicenseRef-Proprietary

{icmd_python-3.3.4.dist-info → icmd_python-3.3.5.dist-info}/RECORD

@@ -1,15 +1,15 @@
 icmd/__init__.py,sha256=BoE6tl0PaBgXqXmL_QjebFos5eOvS91Dj6tjJwolezk,2739
-icmd/client.py,sha256=nqp6MZh2BdT2Qx1cv_Dg306BzvTcHJ1F2Dd0NU1Oh20,22150
+icmd/client.py,sha256=8PXqAskxzkuUwz2wtHYFp9kDAgQlyOxDNbEyVSKayeY,22643
 icmd/compose.py,sha256=V_B4EYuX01oJexnGGvhIwDUKgfx_Fyd0lPVvSRUoH8c,6931
 icmd/links.py,sha256=I8v8_xhI6lbUwrMjIUcYYcqKUi2PIPm6zQ7mXYP9A5E,6827
 icmd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 icmd/types.py,sha256=LizuU96hF7VRjl4OlyF0oPcao1cKe795YXEsLW9fKI4,79496
-icmd/version.py,sha256=Smy9HlTNV-SDgnJHDo2272CgsZJYueox7aaoRhK744k,22
+icmd/version.py,sha256=QO4UWv5ZUgBpuBbLNKWKecIDPPTa5HfOdEYEe2q2Afo,22
 icmd/_vendor/__init__.py,sha256=VFA4EQd2l76sxgkHPUpgzZavFF6kFdpq9v71AZsPIdQ,579
 icmd/_vendor/assembler.py,sha256=U8VPlqN1605RJQ5qMVoNrL3uJ7NpUe8BVmD8q06IN5w,5282
 icmd/apps/__init__.py,sha256=ak2ch1UU-qaiyOT1eCdRwqSI0Avhzyw5DLkw-U2ivQQ,659
 icmd/apps/account.py,sha256=BWDO0Zysv0ygLVhbeIk82BjsvuDVb_vBdu6jqBPw3tc,14557
-icmd/apps/agent.py,sha256=oSgIjchkcWi83-1Bsqywe2yqzfz0cM0XTyidQPoo7IM,8037
+icmd/apps/agent.py,sha256=MmWuH1sYqo-hOhNNuTwh930H_BFXs7oMP0QgyzaC0Iw,8387
 icmd/apps/base.py,sha256=y4uvIiomCLia89UL2rV4oufLBUQaODZ8qwl-EwDtjhM,18979
 icmd/apps/constants.py,sha256=5xoIwFNGOaAp2cHAlVDlbzJ7ObQHYXJgVGMBfNLCHzI,757
 icmd/apps/documents.py,sha256=8_wFc7NLUFQMYZA5hqsciXniHECZEWS-egX_ni8F4LE,3720
@@ -20,8 +20,8 @@ icmd/apps/studio.py,sha256=XN6gVCqkTzp7qH9I-UOhW7UJ2RfkGv60H-G7ulkR850,2419
 icmd/apps/suite.py,sha256=04MIHUima_RGfnHyBPjyxcghcIMHhgDLWPcex6tIWls,2761
 icmd/apps/types.py,sha256=jOzykkXWj9e_lk805_ABCC-sWBwIpJGN3HEb2AyQ9vw,1290
 icmd/apps/workspace.py,sha256=BXCOLQo5BMu-okW2Ink8L_FPhU8r7OWy2jDsvilU3Oo,3055
-icmd/cli/__init__.py,sha256=fTmRemUAxPv5eksJEMtajM01WL0mnXEmrGBidkpyEbA,6944
-icmd/cli/account.py,sha256=8TM-zwOUIJVc11IePT0iL7RC7ZoTBBI5oBMIMW6Ms2Q,13723
+icmd/cli/__init__.py,sha256=mBpAlW1BCKglPzdDffTc4uLdr_2Ri7qnVC2I-Q9FjEA,7395
+icmd/cli/account.py,sha256=equTAGWR3NCCMYEPTw4IZKHEtBEdGD8F4Pp8cfiSNoU,13859
 icmd/cli/auth.py,sha256=UFpEf-lLlkbphivgBfd9NxAEqHcCsPmEl-DXet-NStg,3317
 icmd/cli/auth_status.py,sha256=6wkI3Q0c-t8DBOfuPaN_xXEUcL9HLZm1jX4lQ76X3Ag,13505
 icmd/cli/client.py,sha256=3iToPSABFYWWUPn-uDVFAv9GoBWQXP04l2Id_aYgd64,2186
@@ -36,15 +36,15 @@ icmd/core/advisory.py,sha256=ErXByq5UgpSGkjIiAjnmVCBLdY76REiU-Ilf_HoJ06Y,20783
 icmd/core/auth.py,sha256=bG6eLbSkmyDWLyprx7NJMDwLTGsOIrsRdBZ3f6vz1vk,29480
 icmd/core/constants.py,sha256=P3a01sDt5WmGYqkp5hu4UqWbMgfp50o6rBV3q9jU4yA,2339
 icmd/core/contracts.py,sha256=0Dw7tq_IxQY5YC4CKtaubJ0Npa4Ae66-sm-0UuqH_no,9901
-icmd/core/credentials.py,sha256=Ow3S3RMfvMJL1iJsm_37ZX8T3spk-Rttt80TmsRhUUI,46297
+icmd/core/credentials.py,sha256=39vyoFH1_MrzD9TpTh4FVPhWbrY5X35zGCS22KeTi_8,46835
 icmd/core/display.py,sha256=RkgJhr2Bfw3-ZjGvE100ddD6oyAAUUAJfBAy6DvX5ik,13060
 icmd/core/exceptions.py,sha256=9iFCw93yZ0Eh1x_6-acPU8pVtaUy7EhSz-h1JkYS4M4,6985
 icmd/core/groups.py,sha256=OFbQce42DLDK0rDAdMbh8H7imNPAkBJMl7o7tbKQ4Iw,7211
 icmd/core/model_classes.py,sha256=lOwTwZzmQ247fddFMjPVo43Z_VZfdPhhM0NI8LfRqlc,40047
-icmd/core/session.py,sha256=WWsZDUampgxnPQj-aM5l4OkLS2ZgvSMstjqNCsYAuI0,60054
-icmd_python-3.3.4.dist-info/licenses/LICENSE,sha256=644lGvCmDFa5hQl6xdhaYk3o-1oWqPXAIiiQlvqeZdE,1028
-icmd_python-3.3.4.dist-info/METADATA,sha256=gtyRqOMLEKdmaBoKGd220JkW3pRXZX8a7Etz2kcmhh0,4919
-icmd_python-3.3.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-icmd_python-3.3.4.dist-info/entry_points.txt,sha256=CFX537PlyyPQL3Q_3TKUFeiiDSkOAboqaLEy9AIEwVU,39
-icmd_python-3.3.4.dist-info/top_level.txt,sha256=olzM6Z_QEwg7RrFVOnkgO0I2Ps2m7vhSqYQZYeiawcw,5
-icmd_python-3.3.4.dist-info/RECORD,,
+icmd/core/session.py,sha256=_hdA3Yo_dH1A_qRH1xpyEB8sBkUNQKcUywc54WsPZos,60894
+icmd_python-3.3.5.dist-info/licenses/LICENSE,sha256=644lGvCmDFa5hQl6xdhaYk3o-1oWqPXAIiiQlvqeZdE,1028
+icmd_python-3.3.5.dist-info/METADATA,sha256=YXJOLdFBGc9bfWGYDvIWMAKdFNyPH_WSvSWU32oaBxY,4919
+icmd_python-3.3.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+icmd_python-3.3.5.dist-info/entry_points.txt,sha256=CFX537PlyyPQL3Q_3TKUFeiiDSkOAboqaLEy9AIEwVU,39
+icmd_python-3.3.5.dist-info/top_level.txt,sha256=olzM6Z_QEwg7RrFVOnkgO0I2Ps2m7vhSqYQZYeiawcw,5
+icmd_python-3.3.5.dist-info/RECORD,,