etrade-python 1.0.0__tar.gz → 1.1.0__tar.gz

{etrade_python-1.0.0 → etrade_python-1.1.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased — planned 1.0.0
+## 1.1.0 — 2026-10-17
+
+### Added
+
+- Optional public `CoordinatedCredentialStore` transaction-lock protocol and
+  `CredentialCoordinationError` for sanitized coordination failures.
+- Cross-process OS-backed namespace locks in `KeyringCredentialStore`, with a
+  configurable directory and acquisition timeout, and shared-instance locks in
+  `MemoryCredentialStore`. Credentials and namespace formats remain compatible.
+- Public `SessionManager.revoke()` coordinating broker revocation and local
+  deletion; the existing auth CLI now uses it.
+- Offline subprocess tests using fake shared keyring storage and mocked OAuth.
+
+### Fixed
+
+- Serialize complete lifecycle transactions across cooperating processes, reload
+  credentials under the lock, and preserve newer usage/renewal timestamps when
+  saving the same credentials. Late usage callbacks cannot restore deleted or
+  replaced credentials.
+- Wait for cancelled keyring workers before releasing transaction ownership,
+  including cancellation of pending tasks during event-loop shutdown.
+  Retain credential-free lock files to prevent lock identity replacement races.
+
+## 1.0.0 — 2026-10-11
 
 ### Added
 

{etrade_python-1.0.0 → etrade_python-1.1.0}/CONTRIBUTING.md

@@ -48,6 +48,14 @@ in ordinary CI.
 Test pagination, validation, credential redaction, and retry behavior when changing
 those features. Order mutations must not acquire automatic retries.
 
+Credential lifecycle changes must also test independent session managers and
+actual subprocess contention. Use synthetic keyring backends and HTTPX
+MockTransport; subprocess tests must not access the system keyring or broker.
+Cover replacement/deletion, monotonic timestamps, renewal/revocation, cancellation
+during keyring workers, lock timeouts, namespace isolation, and process-exit lock
+release. A lock must cover the full read/check/update transaction. Report offline
+verification separately from authenticated broker validation.
+
 ## Package verification and releases
 
 After `make package-check`, verify installation outside the source checkout in a

{etrade_python-1.0.0 → etrade_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etrade-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: An unofficial, typed, async-first E*TRADE API client
 Project-URL: Repository, https://github.com/kevinrider/etrade-python
 Project-URL: Issues, https://github.com/kevinrider/etrade-python/issues
@@ -17,8 +17,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: filelock<4,>=3.32.7
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: keyring<26,>=25
+Requires-Dist: platformdirs<5,>=4
 Requires-Dist: pydantic-settings<3,>=2.7
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: typer<1,>=0.20
@@ -32,7 +34,16 @@ Requires-Dist: ruff<1,>=0.11; extra == 'dev'
 Requires-Dist: twine<7,>=6; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# etrade-python
+<div align="center">
+<img src="https://repository-images.githubusercontent.com/1391295794/76df490d-7ec2-48f4-87e8-d4945d37f722" alt="E*TRADE and Python logos above the etrade-python title" width="640">
+</div>
+
+<div align="center">
+<a href="https://github.com/kevinrider/etrade-python/releases"><img src="https://img.shields.io/github/release/kevinrider/etrade-python.svg?style=flat-square" alt="Latest Version"></a>
+<a href="https://github.com/kevinrider/etrade-python/actions/workflows/ci.yml"><img src="https://github.com/kevinrider/etrade-python/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://github.com/kevinrider/etrade-python/issues"><img src="https://img.shields.io/github/issues/kevinrider/etrade-python" alt="GitHub issues"></a>
+<a href="https://github.com/kevinrider/etrade-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kevinrider/etrade-python" alt="License"></a>
+</div>
 
 An unofficial, typed, async-first Python client for the E*TRADE REST API.
 
@@ -40,9 +51,6 @@ An unofficial, typed, async-first Python client for the E*TRADE REST API.
 management, and shared async networking for Python applications, CLIs, background
 workers, web services, workflow engines, and notebooks. Requires Python 3.11+.
 
-The package is prepared for its first stable release, **1.0.0**. The PyPI
-installation instructions below apply once the release is published.
-
 ## Features
 
 - Namespaced Accounts, Portfolio, Transactions, Market, Orders, and Alerts services.
@@ -60,16 +68,16 @@ inspection through Pydantic.
 
 ## Installation
 
-From a source checkout, install into an activated Python 3.11+ virtual environment:
+Install from PyPI into an activated Python 3.11+ virtual environment:
 
 ```sh
-python -m pip install .
+python -m pip install etrade-python
 ```
 
-Once published on PyPI:
+Alternatively, install from a source checkout:
 
 ```sh
-python -m pip install etrade-python
+python -m pip install .
 ```
 
 The distribution name is `etrade-python`; the import package is `etrade_python`.
@@ -141,6 +149,11 @@ contacts the broker even when the token appears active locally.
 
 `auth status` reports a local lifecycle estimate, not broker verification.
 
+`await client.session.revoke()` coordinates broker revocation and local deletion.
+The CLI's `etrade auth revoke` uses this method. Missing credentials are a no-op;
+broker failure preserves the local credentials. Revocation cannot recall an
+already signed or dispatched brokerage request.
+
 ## Accounts and Portfolio
 
 After logging in with the CLI, save this as a Python script and run it with the
@@ -375,6 +388,60 @@ application-managed authorization, then `await client.session.save(credentials)`
 Always close the client after use. Applications can implement the async
 `CredentialStore` protocol for other persistence systems.
 
+### Sharing a profile across local processes
+
+Starting in 1.1.0, session lifecycle operations use namespace transaction locks
+when the store implements `CoordinatedCredentialStore`. The built-in keyring store
+coordinates cooperating SDK/CLI processes using OS-backed file locks. The keyring
+credential format and existing environment/consumer-key/profile namespaces are
+unchanged. Ordinary brokerage HTTP requests remain concurrent; only lifecycle
+transactions are serialized. Automatic inactivity renewal reloads the stored
+credentials after locking, avoiding duplicate renewal by waiting processes.
+Explicit `session.renew()` still contacts the broker on every invocation.
+
+Lock files contain no credentials. They use hashed keyring-service and namespace
+identities in the per-user cache directory `etrade-python/credential-locks` selected
+by platformdirs. Files remain after release to preserve lock identity; OS ownership
+is released when a process exits. Do not delete lock files or clear this cache
+while cooperating processes are running. Use a local filesystem supporting OS
+locks, the same OS user, and the same lock directory for all cooperating processes.
+Older clients and direct uncoordinated store access do not participate.
+
+The keyring lock acquisition timeout defaults to 60 seconds. A timeout, unsupported
+locking, or filesystem failure raises `CredentialCoordinationError` without
+credential/namespace/path details. To configure storage coordination explicitly:
+
+```python
+from pathlib import Path
+from etrade_python import ETradeClient, ETradeSettings, KeyringCredentialStore
+
+store = KeyringCredentialStore(
+    lock_directory=Path("/private/local/path/credential-locks"),
+    lock_timeout_seconds=30,
+)
+client = ETradeClient(ETradeSettings(), credential_store=store, profile="personal")
+```
+
+Every process sharing those credentials must use that same configuration. The
+existing CLI uses the default lock directory. The directory is created on first
+use, with private permissions on POSIX; provision custom directories with
+appropriate access controls. No plaintext credential fallback is introduced.
+
+`MemoryCredentialStore` coordinates managers sharing one store instance within
+one event loop. Existing custom stores implementing only `CredentialStore` remain
+compatible with the earlier per-manager locking guarantee. Custom stores can add
+`lock(namespace) -> AbstractAsyncContextManager[None]` to implement the exported
+`CoordinatedCredentialStore` protocol. Hold that lock across the complete
+read/check/update operation; its `load`, `save`, and `delete` methods must not
+reacquire the non-reentrant lock. Direct store users must explicitly acquire the
+lock themselves. Distributed stores must provide their own appropriate locking.
+
+Cancelled keyring operations finish their worker before releasing transaction
+ownership. This can delay cancellation if the keyring backend is blocked. A process
+crash releases OS lock ownership but does not prove the outcome of an interrupted
+broker renewal or revocation. Recheck/re-authorize as necessary; this mechanism
+does not journal OAuth operations or prevent duplicate trading submissions.
+
 ## Diagnostic CLI and Orders Demo
 
 Use `etrade --help` or `etrade COMMAND --help` to inspect available commands.
@@ -455,7 +522,7 @@ uv run python -m twine check dist/*
 CI checks Python 3.11–3.14, enforces at least 90% combined statement/branch coverage,
 and verifies wheel installation outside the checkout. Push and pull-request CI
 does not publish. A separate release workflow publishes stable GitHub releases
-using PyPI Trusted Publishing once the publisher is configured. See
+using PyPI Trusted Publishing. See
 [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and package verification instructions.
 
 ## API Coverage

{etrade_python-1.0.0 → etrade_python-1.1.0}/README.md

@@ -1,4 +1,13 @@
-# etrade-python
+<div align="center">
+<img src="https://repository-images.githubusercontent.com/1391295794/76df490d-7ec2-48f4-87e8-d4945d37f722" alt="E*TRADE and Python logos above the etrade-python title" width="640">
+</div>
+
+<div align="center">
+<a href="https://github.com/kevinrider/etrade-python/releases"><img src="https://img.shields.io/github/release/kevinrider/etrade-python.svg?style=flat-square" alt="Latest Version"></a>
+<a href="https://github.com/kevinrider/etrade-python/actions/workflows/ci.yml"><img src="https://github.com/kevinrider/etrade-python/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://github.com/kevinrider/etrade-python/issues"><img src="https://img.shields.io/github/issues/kevinrider/etrade-python" alt="GitHub issues"></a>
+<a href="https://github.com/kevinrider/etrade-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kevinrider/etrade-python" alt="License"></a>
+</div>
 
 An unofficial, typed, async-first Python client for the E*TRADE REST API.
 
@@ -6,9 +15,6 @@ An unofficial, typed, async-first Python client for the E*TRADE REST API.
 management, and shared async networking for Python applications, CLIs, background
 workers, web services, workflow engines, and notebooks. Requires Python 3.11+.
 
-The package is prepared for its first stable release, **1.0.0**. The PyPI
-installation instructions below apply once the release is published.
-
 ## Features
 
 - Namespaced Accounts, Portfolio, Transactions, Market, Orders, and Alerts services.
@@ -26,16 +32,16 @@ inspection through Pydantic.
 
 ## Installation
 
-From a source checkout, install into an activated Python 3.11+ virtual environment:
+Install from PyPI into an activated Python 3.11+ virtual environment:
 
 ```sh
-python -m pip install .
+python -m pip install etrade-python
 ```
 
-Once published on PyPI:
+Alternatively, install from a source checkout:
 
 ```sh
-python -m pip install etrade-python
+python -m pip install .
 ```
 
 The distribution name is `etrade-python`; the import package is `etrade_python`.
@@ -107,6 +113,11 @@ contacts the broker even when the token appears active locally.
 
 `auth status` reports a local lifecycle estimate, not broker verification.
 
+`await client.session.revoke()` coordinates broker revocation and local deletion.
+The CLI's `etrade auth revoke` uses this method. Missing credentials are a no-op;
+broker failure preserves the local credentials. Revocation cannot recall an
+already signed or dispatched brokerage request.
+
 ## Accounts and Portfolio
 
 After logging in with the CLI, save this as a Python script and run it with the
@@ -341,6 +352,60 @@ application-managed authorization, then `await client.session.save(credentials)`
 Always close the client after use. Applications can implement the async
 `CredentialStore` protocol for other persistence systems.
 
+### Sharing a profile across local processes
+
+Starting in 1.1.0, session lifecycle operations use namespace transaction locks
+when the store implements `CoordinatedCredentialStore`. The built-in keyring store
+coordinates cooperating SDK/CLI processes using OS-backed file locks. The keyring
+credential format and existing environment/consumer-key/profile namespaces are
+unchanged. Ordinary brokerage HTTP requests remain concurrent; only lifecycle
+transactions are serialized. Automatic inactivity renewal reloads the stored
+credentials after locking, avoiding duplicate renewal by waiting processes.
+Explicit `session.renew()` still contacts the broker on every invocation.
+
+Lock files contain no credentials. They use hashed keyring-service and namespace
+identities in the per-user cache directory `etrade-python/credential-locks` selected
+by platformdirs. Files remain after release to preserve lock identity; OS ownership
+is released when a process exits. Do not delete lock files or clear this cache
+while cooperating processes are running. Use a local filesystem supporting OS
+locks, the same OS user, and the same lock directory for all cooperating processes.
+Older clients and direct uncoordinated store access do not participate.
+
+The keyring lock acquisition timeout defaults to 60 seconds. A timeout, unsupported
+locking, or filesystem failure raises `CredentialCoordinationError` without
+credential/namespace/path details. To configure storage coordination explicitly:
+
+```python
+from pathlib import Path
+from etrade_python import ETradeClient, ETradeSettings, KeyringCredentialStore
+
+store = KeyringCredentialStore(
+    lock_directory=Path("/private/local/path/credential-locks"),
+    lock_timeout_seconds=30,
+)
+client = ETradeClient(ETradeSettings(), credential_store=store, profile="personal")
+```
+
+Every process sharing those credentials must use that same configuration. The
+existing CLI uses the default lock directory. The directory is created on first
+use, with private permissions on POSIX; provision custom directories with
+appropriate access controls. No plaintext credential fallback is introduced.
+
+`MemoryCredentialStore` coordinates managers sharing one store instance within
+one event loop. Existing custom stores implementing only `CredentialStore` remain
+compatible with the earlier per-manager locking guarantee. Custom stores can add
+`lock(namespace) -> AbstractAsyncContextManager[None]` to implement the exported
+`CoordinatedCredentialStore` protocol. Hold that lock across the complete
+read/check/update operation; its `load`, `save`, and `delete` methods must not
+reacquire the non-reentrant lock. Direct store users must explicitly acquire the
+lock themselves. Distributed stores must provide their own appropriate locking.
+
+Cancelled keyring operations finish their worker before releasing transaction
+ownership. This can delay cancellation if the keyring backend is blocked. A process
+crash releases OS lock ownership but does not prove the outcome of an interrupted
+broker renewal or revocation. Recheck/re-authorize as necessary; this mechanism
+does not journal OAuth operations or prevent duplicate trading submissions.
+
 ## Diagnostic CLI and Orders Demo
 
 Use `etrade --help` or `etrade COMMAND --help` to inspect available commands.
@@ -421,7 +486,7 @@ uv run python -m twine check dist/*
 CI checks Python 3.11–3.14, enforces at least 90% combined statement/branch coverage,
 and verifies wheel installation outside the checkout. Push and pull-request CI
 does not publish. A separate release workflow publishes stable GitHub releases
-using PyPI Trusted Publishing once the publisher is configured. See
+using PyPI Trusted Publishing. See
 [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and package verification instructions.
 
 ## API Coverage

{etrade_python-1.0.0 → etrade_python-1.1.0}/SECURITY.md

@@ -2,8 +2,7 @@
 
 `etrade-python` implements OAuth authentication and brokerage operations, including
 order placement, changes, and cancellation. Production mutations affect real
-brokerage accounts. The first stable release is planned as 1.0.0; until it is
-published, security fixes target the development branch.
+brokerage accounts. The supported release series is 1.1.x. Use the latest available patch release.
 
 ## Reporting vulnerabilities
 
@@ -31,9 +30,24 @@ A dedicated security contact has not yet been published.
   Completed HTTP 2xx exchanges do, even if later payload parsing fails. Failed or
   cancelled exchanges do not. Explicit renewal contacts the broker, and timestamps
   are persisted only after successful renewal.
-- Updates within a session manager are serialized and preserve newer timestamps.
-  Late responses do not restore deleted or replaced credentials. Custom stores
-  used across multiple processes must provide their own concurrency guarantees.
+- In 1.1.0, built-in keyring session updates are coordinated across cooperating
+  processes and preserve newer timestamps. Late usage updates do not restore
+  deleted or replaced credentials. Namespace locks cover complete lifecycle
+  transactions, including broker renewal and revocation, rather than brokerage
+  HTTP calls. Existing custom stores remain compatible but must implement the
+  optional `CoordinatedCredentialStore` contract for shared-store coordination.
+  Old clients and direct store writes bypass these guarantees.
+- Lock files contain no credentials and use hashed namespace/service identities.
+  All cooperating processes must use the same per-user lock directory on a local
+  filesystem supporting OS locks. Private directories and files are used; existing
+  custom directory permissions are the caller's responsibility. Do not delete
+  lock files or clear the directory while clients are running. No soft-lock or
+  unlocked fallback is allowed. OS lock ownership is released on process exit.
+- Keyring worker cancellation is deferred until the worker completes so a late
+  write cannot run after transaction ownership is released. A blocked keyring can
+  delay cancellation. A process crash or lost OAuth response still leaves broker
+  outcomes uncertain; locks do not provide crash-atomic broker/keyring changes.
+  Revocation cannot recall already signed or dispatched requests.
   If usage persistence fails after a successful API exchange, the library logs a
   sanitized warning and preserves the broker response without retrying it.
 

{etrade_python-1.0.0 → etrade_python-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "etrade-python"
-version = "1.0.0"
+version = "1.1.0"
 description = "An unofficial, typed, async-first E*TRADE API client"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,6 +22,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "filelock>=3.32.7,<4",
+  "platformdirs>=4,<5",
   "httpx>=0.28,<1",
   "keyring>=25,<26",
   "pydantic>=2.10,<3",

{etrade_python-1.0.0 → etrade_python-1.1.0}/src/etrade_python/__init__.py

@@ -20,6 +20,7 @@ from etrade_python.alerts import (
 )
 from etrade_python.auth import (
     AuthorizationUrl,
+    CoordinatedCredentialStore,
     CredentialStore,
     ETradeCredentials,
     KeyringCredentialStore,
@@ -38,6 +39,7 @@ from etrade_python.enums import Environment
 from etrade_python.exceptions import (
     AuthenticationRequired,
     AuthorizationExpired,
+    CredentialCoordinationError,
     ETradeApiError,
     ETradeAuthenticationError,
     ETradeError,
@@ -201,6 +203,7 @@ __all__ = [
     "CancelOrderResponse",
     "CancelOrderRequest",
     "AuthenticationRequired",
+    "CredentialCoordinationError",
     "Account",
     "AccountBalanceRequest",
     "AccountBalanceResponse",
@@ -208,6 +211,7 @@ __all__ = [
     "AccountsService",
     "AuthorizationUrl",
     "AuthorizationExpired",
+    "CoordinatedCredentialStore",
     "CredentialStore",
     "ETradeApiError",
     "ETradeAuthenticationError",

{etrade_python-1.0.0 → etrade_python-1.1.0}/src/etrade_python/_version.py

@@ -1,3 +1,3 @@
 """Runtime version shared by the public package and HTTP transport."""
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"

{etrade_python-1.0.0 → etrade_python-1.1.0}/src/etrade_python/auth/__init__.py

@@ -10,6 +10,7 @@ from etrade_python.auth.credentials import (
 from etrade_python.auth.oauth import OAuthClient
 from etrade_python.auth.session import SessionAuthenticator, SessionManager, TokenStatus
 from etrade_python.auth.stores import (
+    CoordinatedCredentialStore,
     CredentialStore,
     KeyringCredentialStore,
     MemoryCredentialStore,
@@ -17,6 +18,7 @@ from etrade_python.auth.stores import (
 
 __all__ = [
     "AuthorizationUrl",
+    "CoordinatedCredentialStore",
     "CredentialStore",
     "ETradeCredentials",
     "KeyringCredentialStore",

{etrade_python-1.0.0 → etrade_python-1.1.0}/src/etrade_python/auth/session.py

@@ -2,7 +2,8 @@
 
 import asyncio
 import hashlib
-from collections.abc import Awaitable, Callable
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
 from datetime import UTC, datetime, timedelta
 from enum import StrEnum
 from zoneinfo import ZoneInfo
@@ -11,7 +12,7 @@ import httpx
 
 from etrade_python.auth.credentials import ETradeCredentials
 from etrade_python.auth.oauth import OAuthClient
-from etrade_python.auth.stores.base import CredentialStore
+from etrade_python.auth.stores.base import CoordinatedCredentialStore, CredentialStore
 from etrade_python.config import ETradeSettings
 from etrade_python.exceptions import AuthenticationRequired, AuthorizationExpired
 
@@ -48,10 +49,23 @@ class SessionManager:
         self._clock = clock or (lambda: datetime.now(UTC))
         self._renewal_lock = asyncio.Lock()
 
-    async def ensure_active(self) -> ETradeCredentials:
+    @asynccontextmanager
+    async def _transaction(self) -> AsyncGenerator[None]:
         async with self._renewal_lock:
+            if isinstance(self._credential_store, CoordinatedCredentialStore):
+                async with self._credential_store.lock(self._storage_key):
+                    yield
+            else:
+                # Preserve the original contract for existing custom stores.
+                yield
+
+    async def _load(self) -> ETradeCredentials | None:
+        return await self._credential_store.load(self._storage_key)
+
+    async def ensure_active(self) -> ETradeCredentials:
+        async with self._transaction():
             now = self._now()
-            credentials = await self.load()
+            credentials = await self._load()
             status = self.status(credentials, now=now)
             if status is TokenStatus.MISSING:
                 raise AuthenticationRequired("E*TRADE authorization is required")
@@ -65,8 +79,8 @@ class SessionManager:
 
     async def renew(self) -> ETradeCredentials:
         """Renew same-day credentials with the broker, even when locally active."""
-        async with self._renewal_lock:
-            credentials = await self.load()
+        async with self._transaction():
+            credentials = await self._load()
             if credentials is None:
                 raise AuthenticationRequired("E*TRADE authorization is required")
             if self.status(credentials) is TokenStatus.EXPIRED:
@@ -76,34 +90,56 @@ class SessionManager:
     async def _renew(self, credentials: ETradeCredentials) -> ETradeCredentials:
         """Perform renewal while the caller holds the renewal lock."""
         result = await self._oauth_client.renew_access_token(credentials)
-        renewed = result.credentials.with_renewal(self._now())
+        renewed = result.credentials.with_renewal(max(self._now(), credentials.last_used_at))
+        if credentials.renewed_at is not None and (
+            renewed.renewed_at is None or credentials.renewed_at > renewed.renewed_at
+        ):
+            renewed = renewed.model_copy(update={"renewed_at": credentials.renewed_at})
         await self._save(renewed)
         return renewed
 
     async def save(self, credentials: ETradeCredentials) -> None:
-        async with self._renewal_lock:
+        async with self._transaction():
+            current = await self._load()
+            if current is not None and _same_credentials(current, credentials):
+                renewed = [t for t in (current.renewed_at, credentials.renewed_at) if t is not None]
+                credentials = credentials.model_copy(
+                    update={
+                        "last_used_at": max(current.last_used_at, credentials.last_used_at),
+                        "renewed_at": max(renewed) if renewed else None,
+                    }
+                )
             await self._save(credentials)
 
     async def _save(self, credentials: ETradeCredentials) -> None:
         await self._credential_store.save(self._storage_key, credentials)
 
     async def load(self) -> ETradeCredentials | None:
-        return await self._credential_store.load(self._storage_key)
+        async with self._transaction():
+            return await self._load()
 
     async def delete(self) -> None:
-        async with self._renewal_lock:
+        async with self._transaction():
             await self._credential_store.delete(self._storage_key)
 
+    async def revoke(self) -> None:
+        """Revoke current credentials and delete locally only after broker success.
+
+        This coordinates lifecycle updates, not already-dispatched API requests.
+        Missing credentials are a no-op. Broker errors preserve local credentials.
+        """
+        async with self._transaction():
+            credentials = await self._load()
+            if credentials is not None:
+                await self._oauth_client.revoke_access_token(credentials)
+                await self._credential_store.delete(self._storage_key)
+
     async def record_usage(self, credentials: ETradeCredentials) -> None:
         """Record confirmed usage without overwriting newer or replaced credentials."""
         used_at = self._now()
-        async with self._renewal_lock:
-            current = await self.load()
-            if current is None or (
-                current.access_token != credentials.access_token
-                or current.access_token_secret != credentials.access_token_secret
-                or current.acquired_at != credentials.acquired_at
-            ):
+        async with self._transaction():
+            current = await self._load()
+            if current is None or not _same_credentials(current, credentials):
                 return
             if used_at > current.last_used_at:
                 await self._save(current.with_last_used(used_at))
@@ -137,6 +173,14 @@ class SessionManager:
         return value.astimezone(UTC)
 
 
+def _same_credentials(left: ETradeCredentials, right: ETradeCredentials) -> bool:
+    return (
+        left.access_token == right.access_token
+        and left.access_token_secret == right.access_token_secret
+        and left.acquired_at == right.acquired_at
+    )
+
+
 class SessionAuthenticator:
     """Transport authenticator backed by SessionManager credentials."""
 

etrade_python-1.1.0/src/etrade_python/auth/stores/__init__.py

@@ -0,0 +1,12 @@
+"""Credential store implementations."""
+
+from etrade_python.auth.stores.base import CoordinatedCredentialStore, CredentialStore
+from etrade_python.auth.stores.keyring import KeyringCredentialStore
+from etrade_python.auth.stores.memory import MemoryCredentialStore
+
+__all__ = [
+    "CoordinatedCredentialStore",
+    "CredentialStore",
+    "KeyringCredentialStore",
+    "MemoryCredentialStore",
+]

etrade_python-1.1.0/src/etrade_python/auth/stores/_workers.py

@@ -0,0 +1,44 @@
+"""Wait for keyring and lock workers before relinquishing transaction ownership."""
+
+import asyncio
+import contextvars
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+async def run_worker(function: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
+    """Defer cancellation until a worker finishes, including repeated cancellation.
+
+    A worker thread cannot be stopped by cancelling its awaiter. Releasing a
+    namespace lock first would allow its late write to race with the next owner.
+    """
+    context = contextvars.copy_context()
+    # Use an executor Future, not a Task: asyncio.run() cancels all Tasks during
+    # shutdown, including a shielded to_thread Task. This Future stays alive until
+    # the actual thread finishes, so the transaction cannot unlock prematurely.
+    worker = asyncio.get_running_loop().run_in_executor(
+        None, lambda: context.run(function, *args, **kwargs)
+    )
+    cancelled = False
+    while True:
+        try:
+            result = await asyncio.shield(worker)
+        except asyncio.CancelledError:
+            cancelled = True
+            if not worker.done():
+                continue
+            # Retrieve worker exceptions even when cancellation wins.
+            if not worker.cancelled():
+                worker.exception()
+            raise
+        except Exception:
+            if cancelled:
+                raise asyncio.CancelledError from None
+            raise
+        else:
+            if cancelled:
+                raise asyncio.CancelledError
+            return result

etrade_python-1.1.0/src/etrade_python/auth/stores/base.py

@@ -0,0 +1,33 @@
+"""Credential store protocol."""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol, runtime_checkable
+
+from etrade_python.auth.credentials import ETradeCredentials
+
+
+class CredentialStore(Protocol):
+    """Async persistence boundary for OAuth credentials."""
+
+    async def load(self, profile: str) -> ETradeCredentials | None:
+        """Load credentials for a profile, returning None when absent."""
+
+    async def save(self, profile: str, credentials: ETradeCredentials) -> None:
+        """Persist credentials for a profile."""
+
+    async def delete(self, profile: str) -> None:
+        """Delete credentials for a profile."""
+
+
+@runtime_checkable
+class CoordinatedCredentialStore(CredentialStore, Protocol):
+    """Optional transaction lock shared by all users of a credential namespace.
+
+    SessionManager holds this lock across complete lifecycle operations. Store
+    methods must not reacquire it. Direct store users must explicitly acquire it
+    around read/modify/write sequences. Locks need not be reentrant.
+    """
+
+    def lock(self, namespace: str) -> AbstractAsyncContextManager[None]:
+        """Exclusively coordinate a namespace, releasing ownership on exit."""
+        ...