ctrader-api-client 0.10.0__tar.gz → 0.11.0__tar.gz

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrader-api-client
-Version: 0.10.0
+Version: 0.11.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -133,6 +133,9 @@ await client.auth.authenticate_trader(
 # Tokens are automatically refreshed before expiry. A refresh that fails is
 # retried on the next check rather than dropping the session, and surfaces as a
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
+# An access token that has already expired is refreshed before the account is
+# authenticated, so a process that starts after the expiry needs no new token.
+# Only a refresh token the server refuses raises TokenExpiredError.
 ```
 
 ### Persisting Rotated Tokens

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/README.md

@@ -114,6 +114,9 @@ await client.auth.authenticate_trader(
 # Tokens are automatically refreshed before expiry. A refresh that fails is
 # retried on the next check rather than dropping the session, and surfaces as a
 # TokenRefreshFailedEvent so a persistently dead refresh token is observable.
+# An access token that has already expired is refreshed before the account is
+# authenticated, so a process that starts after the expiry needs no new token.
+# Only a refresh token the server refuses raises TokenExpiredError.
 ```
 
 ### Persisting Rotated Tokens

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/docs/api/client.md

@@ -70,7 +70,9 @@ Token-refresh and session-recovery timing, passed via
 
 The `client.auth` property provides access to authentication operations. The
 application is authenticated as the client connects, so what is left here is
-authenticating trading accounts and asking after the sessions they hold.
+authenticating trading accounts and asking after the sessions they hold. An
+account whose access token has expired is refreshed before it is authenticated,
+so the refresh token in the credentials is what a restart depends on.
 
 ::: ctrader_api_client.auth.AuthManager
     options:

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/docs/api/exceptions.md

@@ -19,7 +19,7 @@ CTraderError
 ├── AuthenticationError
 │   ├── ApplicationAuthError            the server rejected client_id/secret
 │   ├── AccountAuthError                the server rejected the account
-│   ├── TokenExpiredError               the access token is expired or invalid
+│   ├── TokenExpiredError               the server refused the access or refresh token
 │   ├── TokenRefreshError               a refresh exhausted its retries
 │   └── AccountNotFoundError            no account matches that trader login
 ├── APIError                            an error response to a request
@@ -69,9 +69,11 @@ except AccountAuthError as e:
     print(f"Account {e.ctid_trader_account_id} rejected: {e.error_code}")
 ```
 
-`TokenExpiredError` covers both a token the client knows has expired and one the
-server rejects as invalid. Neither can be retried back to life — it needs a new
-token.
+`TokenExpiredError` means the server refused a token: the access token at
+authentication, or the refresh token when the client refreshed an expired access
+token first. Neither can be retried back to life. It needs a new OAuth
+authorization. An access token that has merely expired does not raise, because
+the client refreshes it before it authenticates the account.
 
 ### Requests
 

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/docs/getting-started.md

@@ -235,6 +235,12 @@ The contract is write-only. Reading back at startup is yours, since only you kno
 which accounts a given process is responsible for. See
 [TokenStore](api/client.md#tokenstore) for the full contract.
 
+A stored pair whose access token has expired still works. `authenticate_trader`
+refreshes it first and saves the new pair through the store, so a process that
+starts after the expiry needs no new token from the outside. Only a refresh token
+that the server refuses raises `TokenExpiredError`, and that needs a new OAuth
+authorization.
+
 ## Handling Errors
 
 Everything the library raises derives from `CTraderError`. Bringing the client up

ctrader_api_client-0.11.0/plans/startup-token-refresh.md

@@ -0,0 +1,157 @@
+# Startup token refresh
+
+Status: complete on 2026-09-27 in 0.11.0, commits `ee431d9`, `de5037f`,
+`5869d89`, `92c2f79`, and `ec6d29f`. The consumer follow-up is pending.
+
+## Problem
+
+An expired access token is terminal, although the credentials that hold it also
+hold a refresh token that would replace it.
+
+- `AuthManager.establish` raises `TokenExpiredError` when `credentials.is_expired()`
+  is true. It sends no request first.
+- The refresh exchange lives only in `SessionMaintainer._rotate`. Only the refresh
+  loop reaches it, and the loop runs only while the client is open.
+
+So a token that expires while no client is open is dead on the next start. This
+hits every process that is not a long-lived daemon. A daily job that runs for
+minutes never sits in the five-minute refresh window, so its token always expires
+between runs. A long-lived process hits the same wall after a link outage that
+spans the expiry: `prepare` re-establishes each account with the expired token and
+fails.
+
+## Facts from the source
+
+- `auth/manager.py`: `establish` guards with `is_expired()` before the
+  `ProtoOAAccountAuthReq`. `authenticate_trader`, `SessionMaintainer.prepare`,
+  `SessionMaintainer._recover`, and `SessionMaintainer._rotate` all call it.
+- `auth/_maintain.py`: `_rotate` sends `ProtoOARefreshTokenReq`, maps a token
+  failure to `TokenExpiredError`, calls `manager.replace_credentials`, saves through
+  the token store, then calls `establish` with `AuthTrigger.TOKEN_REFRESH`. The
+  new pair goes into memory before the save, because the server has invalidated
+  the old pair.
+- `_refresh` wraps `_rotate` with the retry policy and the refresh window
+  (`_refreshing`). The window exists so that the disconnect report the server sends
+  for the old authorization is not read as a drop.
+- `AuthManager.replace_credentials` creates a `TrackedAccount` with no session for
+  an account id it does not hold.
+- `tests/behavior/auth/test_token_lifecycle.py` pins the refresh loop: the request
+  carries the current refresh token, the new pair is saved, a dead refresh token is
+  not retried, a store that cannot save aborts the refresh, and a check refused over
+  the token leaves the account alone.
+- `tests/behavior/auth/test_authentication.py::test_an_already_expired_token_is_not_sent_to_the_server`
+  pins the current terminal behaviour.
+- `RefreshPolicy.buffer_seconds` drives the loop only.
+
+## Design
+
+1. `AuthManager` gains `refresh(credentials, timeout=None) -> AccountCredentials`.
+   It sends the refresh request, maps a token failure to `TokenExpiredError`,
+   calls `replace_credentials`, and saves through the token store. This is the
+   body of `_rotate` today, moved. The manager takes `token_store`; the
+   maintainer no longer does.
+2. `establish` replaces the guard `if is_expired: raise` with
+   `credentials = await self.refresh(credentials)`. Every path that establishes a
+   session gets the behaviour from the one place that owned the decision. No
+   caller changes.
+3. `SessionMaintainer._rotate` becomes: `rotated = await manager.refresh(c)`, then
+   `establish(rotated, TOKEN_REFRESH)`. The retry policy, the refresh window, and
+   the `TokenRefreshFailedEvent` stay in the maintainer. The maintainer drops the
+   token store and the proto imports.
+4. `replace_credentials` does nothing for an account id it does not hold. The
+   name promises a replacement, and an account tracked before it ever
+   authenticated is a latent bug: `prepare` would try to re-establish it.
+5. The library ships no `TokenStore` implementation. The protocol stays
+   write-only, and each consumer keeps its own store, because only the consumer
+   knows which accounts a process holds and where they live. A shipped file
+   store was in an earlier version of this plan and was dropped on 2026-09-27:
+   only one consumer wants a file, and a `load_all` on a shipped store would
+   assert a one-file-one-process model that the library has no business
+   asserting.
+
+### What does not change
+
+- `refresh` makes one attempt. A refused refresh token raises `TokenExpiredError`.
+  Another refusal raises the `APIError`. A timeout propagates. The maintainer keeps
+  its retry-and-report wrapping around the same call.
+- The new pair goes into memory before the save. A store that cannot save raises,
+  and the account is not authenticated, because a pair the store never accepted
+  strands the next restart. This is the stance the lifecycle tests pin today.
+- No refresh window at the three new refresh points. No live authorization exists
+  there: the account is not tracked yet, or `prepare` invalidated it, or it awaits
+  recovery. The existing test that a check refused over the token leaves the
+  account alone covers the case where a report arrives anyway.
+- `_recover` defers on any exception, with no attempt limit. A dead refresh token
+  is retried the same way an expired token is today.
+- `buffer_seconds` plays no part at startup. Only `is_expired` triggers a refresh
+  in `establish`. A token with time left is established as today, and the loop
+  handles "expires soon" with its retries.
+
+### Attribute counts
+
+- `AuthManager`: 7 today, 8 after (`_token_store`).
+- `SessionMaintainer`: 9 today, 7 after (`_token_store` leaves, and `_protocol`
+  leaves with it, because the refresh exchange was its only use). Agreed during
+  step 2.
+
+## Steps
+
+One step per turn. Each step leaves the suite green.
+
+### Step 1: `replace_credentials` ignores an unknown account
+
+`auth/manager.py` only. One new test in `test_authentication.py`: replacing the
+credentials of an account the manager does not hold leaves the manager without
+that account.
+
+### Step 2: move the refresh exchange to the manager
+
+- `AuthManager.__init__` takes `token_store: TokenStore | None = None`.
+- Add `AuthManager.refresh`.
+- `SessionMaintainer.__init__` drops `token_store`. `_rotate` calls
+  `manager.refresh`. Remove the proto imports and `TokenStore` import from
+  `_maintain.py`.
+- `composition.build_graph` passes `token_store` to `AuthManager`.
+- `tests/behavior/auth/conftest.py`: a `store` fixture returns a `RecordingStore`.
+  `make_auth` passes it as `token_store`. `make_maintainer` accepts a `manager`
+  override for a test that builds its own manager. The tests that construct a
+  `RecordingStore` build the manager with it through `make_auth` instead of
+  passing it to `make_maintainer`.
+
+Every assertion in `test_token_lifecycle.py` passes unchanged.
+
+### Step 3: `establish` refreshes an expired token
+
+- `auth/manager.py`: the guard becomes the refresh call.
+- Replace `test_an_already_expired_token_is_not_sent_to_the_server` in
+  `test_authentication.py` with:
+  1. An expired token is refreshed before the account is authenticated: the auth
+     request carries the new token, the store saved it, and the expired token was
+     not sent.
+  2. An expired token whose refresh is refused raises `TokenExpiredError`, and no
+     auth request is sent.
+  3. A token with time left is not refreshed at authentication.
+- Add to `test_token_lifecycle.py`:
+  4. A new link refreshes an expired account before it re-establishes it:
+     `maintainer.prepare()` with an expired tracked account sends the refresh
+     request, then the auth request with the new token.
+
+### Step 4: docs and version
+
+- `README.md` and `docs/getting-started.md`: state that `authenticate_trader`
+  refreshes an expired access token, and what it raises. The file store example
+  in the getting-started guide stays as consumer code.
+- `docs/api/exceptions.md`: `TokenExpiredError` now means a token the server
+  refused. A token the client knows has expired is refreshed instead. Added
+  during step 3.
+- `pyproject.toml`: 0.11.0.
+
+## Consumer follow-up
+
+Out of scope for this repository. Recorded so the two changes stay aligned.
+
+The framework bumps its pin to 0.11.0 and adds its own file-backed `TokenStore`
+with a `CTRADER_TOKEN_FILE` setting, default `.ctrader-tokens.json`. It saves
+the bootstrap pair from `.env` on the first run after it resolves the account
+id, and reads the stored pair back on later runs. A publish deployment has one
+broker account, so a file with more than one entry is an error.

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.10.0"
+version = "0.11.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/src/ctrader_api_client/auth/_maintain.py

@@ -9,13 +9,11 @@ that the server drops, and prepares each new link.
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
 
 import anyio
 import anyio.abc
 
 from .._internal import Clock, MonotonicClock, backoff_delay
-from .._internal.proto import ProtoOARefreshTokenReq, ProtoOARefreshTokenRes
 from ..enums import AuthTrigger
 from ..events import (
     AccountDisconnectEvent,
@@ -24,16 +22,11 @@ from ..events import (
     ReconnectedEvent,
     TokenRefreshFailedEvent,
 )
-from ..exceptions import AccountAuthError, APIError, TokenExpiredError, TokenRefreshError
+from ..exceptions import AccountAuthError, APIError, TokenRefreshError
 from ._session import AwaitingRecovery
 from .credentials import AccountCredentials
 from .manager import AuthManager
 from .policy import ReauthPolicy, RefreshPolicy
-from .store import TokenStore
-
-
-if TYPE_CHECKING:
-    from ..connection.protocol import Protocol
 
 
 logger = logging.getLogger(__name__)
@@ -66,34 +59,27 @@ class SessionMaintainer:
 
     def __init__(
         self,
-        protocol: Protocol,
         manager: AuthManager,
         publisher: EventPublisher,
         refresh_policy: RefreshPolicy | None = None,
         reauth_policy: ReauthPolicy | None = None,
         clock: Clock | None = None,
-        token_store: TokenStore | None = None,
     ) -> None:
         """Initialize the maintainer.
 
         Args:
-            protocol: The protocol that sends the refresh requests.
-            manager: Holds the accounts, and authenticates the application and
-                the accounts.
+            manager: Holds the accounts, refreshes their tokens, and
+                authenticates the application and the accounts.
             publisher: Where the events are published.
             refresh_policy: When to refresh access tokens, and how hard to try.
             reauth_policy: Backoff for the sessions that the server dropped.
             clock: Time source for the refresh interval and the backoff.
-            token_store: Durable storage for rotated credentials. Without one,
-                refreshed tokens live only in memory.
         """
-        self._protocol = protocol
         self._manager = manager
         self._publisher = publisher
         self._refresh_policy = refresh_policy if refresh_policy is not None else RefreshPolicy()
         self._reauth_policy = reauth_policy if reauth_policy is not None else ReauthPolicy()
         self._clock = clock if clock is not None else MonotonicClock()
-        self._token_store = token_store
 
         # Set when an account needs recovery. The recovery loop replaces it
         # each time it wakes.
@@ -307,32 +293,11 @@ class SessionMaintainer:
             settled.set()
 
     async def _rotate(self, credentials: AccountCredentials) -> None:
-        """Make one refresh exchange, keep the new pair, and re-authorize the account.
-
-        The server invalidates the old pair as it issues the new one, so the
-        new pair is kept before the store saves it.
+        """Make one refresh exchange and re-authorize the account with the new pair.
 
         Raises:
             TokenExpiredError: If the refresh token is dead.
             APIError: If the server refuses the request for another reason.
         """
-        request = ProtoOARefreshTokenReq(refresh_token=credentials.refresh_token)
-        try:
-            response = await self._protocol.request(request, ProtoOARefreshTokenRes)
-        except APIError as e:
-            if e.is_token_failure():
-                raise TokenExpiredError(credentials.account_id) from e
-            raise
-
-        rotated = credentials.with_refreshed_tokens(
-            access_token=response.access_token,
-            refresh_token=response.refresh_token,
-            expires_in=response.expires_in,
-        )
-        self._manager.replace_credentials(rotated)
-
-        if self._token_store is not None:
-            await self._token_store.save(rotated)
-
-        logger.debug("Token refreshed for account %d, new expiry in %ds", credentials.account_id, response.expires_in)
+        rotated = await self._manager.refresh(credentials)
         await self._manager.establish(rotated, AuthTrigger.TOKEN_REFRESH)

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/src/ctrader_api_client/auth/manager.py

@@ -15,6 +15,8 @@ from .._internal.proto import (
     ProtoOAAccountAuthRes,
     ProtoOAApplicationAuthReq,
     ProtoOAApplicationAuthRes,
+    ProtoOARefreshTokenReq,
+    ProtoOARefreshTokenRes,
     ProtoOATraderReq,
     ProtoOATraderRes,
 )
@@ -28,6 +30,7 @@ from ..exceptions import (
 )
 from ._session import Authorized, AwaitingRecovery, TrackedAccount
 from .credentials import AccountCredentials
+from .store import TokenStore
 
 
 if TYPE_CHECKING:
@@ -75,6 +78,7 @@ class AuthManager:
         client_id: str,
         client_secret: str,
         restorer: SessionRestorer | None = None,
+        token_store: TokenStore | None = None,
     ) -> None:
         """Initialize the authentication manager.
 
@@ -85,12 +89,15 @@ class AuthManager:
             client_secret: OAuth client secret for the application.
             restorer: Re-applies whatever a fresh session starts without, before
                 the account is announced as ready.
+            token_store: Durable storage for rotated credentials. Without one,
+                refreshed tokens live only in memory.
         """
         self._protocol = protocol
         self._publisher = publisher
         self._client_id = client_id
         self._client_secret = client_secret
         self._restorer = restorer
+        self._token_store = token_store
         self._app_authenticated = False
         self._accounts: dict[int, TrackedAccount] = {}
 
@@ -154,16 +161,15 @@ class AuthManager:
         self._accounts[credentials.account_id] = TrackedAccount(credentials, Authorized())
 
     def replace_credentials(self, credentials: AccountCredentials) -> None:
-        """Swap in rotated tokens. Leave the session state as it was.
+        """Swap in rotated tokens for an account the manager holds. Leave the session state as it was.
 
         Args:
             credentials: The rotated credentials.
         """
         current = self._accounts.get(credentials.account_id)
-        self._accounts[credentials.account_id] = TrackedAccount(
-            credentials,
-            current.session if current is not None else None,
-        )
+        if current is None:
+            return
+        self._accounts[credentials.account_id] = TrackedAccount(credentials, current.session)
 
     def invalidate_all(self) -> None:
         """Forget every server-side session. Keep the credentials.
@@ -255,16 +261,19 @@ class AuthManager:
     ) -> None:
         """Authenticate a trading account and keep its session alive.
 
-        The credentials are kept, so the tokens are refreshed before they
-        expire and the session is re-established after a disconnect.
+        An expired access token is refreshed first. The credentials are kept,
+        so the tokens are refreshed before they expire and the session is
+        re-established after a disconnect.
 
         Args:
             credentials: The account credentials including tokens.
             timeout: Request timeout in seconds. None uses the configured default.
 
         Raises:
-            TokenExpiredError: If the access token has expired or the server
-                rejects it as invalid.
+            TokenExpiredError: If the server rejects the access token, or if
+                the access token has expired and the server rejects the
+                refresh token.
+            APIError: If the server refuses a refresh for another reason.
             AccountAuthError: If the server rejects the account.
             CTraderConnectionTimeoutError: If request times out.
         """
@@ -278,6 +287,9 @@ class AuthManager:
     ) -> None:
         """Authorize an account on the current link.
 
+        An expired access token is refreshed first, so a process that starts
+        or reconnects after the expiry needs no new token from the outside.
+
         Args:
             credentials: The account credentials including tokens.
             trigger: Why the authentication happens. A token refresh renews
@@ -287,8 +299,10 @@ class AuthManager:
             timeout: Request timeout in seconds. None uses the configured default.
 
         Raises:
-            TokenExpiredError: If the access token has expired or the server
-                rejects it as invalid.
+            TokenExpiredError: If the server rejects the access token, or if
+                the access token has expired and the server rejects the
+                refresh token.
+            APIError: If the server refuses a refresh for another reason.
             AccountAuthError: If the server rejects the account.
             CTraderConnectionTimeoutError: If request times out.
         """
@@ -298,7 +312,8 @@ class AuthManager:
             logger.debug("Re-authenticating account %d (%s)", credentials.account_id, trigger.value)
 
         if credentials.is_expired():
-            raise TokenExpiredError(credentials.account_id)
+            logger.debug("Access token for account %d has expired; refreshing first", credentials.account_id)
+            credentials = await self.refresh(credentials, timeout=timeout)
 
         request = ProtoOAAccountAuthReq(
             ctid_trader_account_id=credentials.account_id,
@@ -323,6 +338,45 @@ class AuthManager:
                 await self._restorer.restore(credentials.account_id)
             await self._publisher.emit(ReadyEvent(account_id=credentials.account_id, trigger=trigger))
 
+    async def refresh(self, credentials: AccountCredentials, timeout: float | None = None) -> AccountCredentials:
+        """Rotate the tokens of an account and keep the new pair.
+
+        The server invalidates the old pair as it issues the new one, so the new
+        pair replaces the held one before the store saves it.
+
+        Args:
+            credentials: The credentials whose refresh token is presented.
+            timeout: Request timeout in seconds. None uses the configured default.
+
+        Returns:
+            The rotated credentials.
+
+        Raises:
+            TokenExpiredError: If the refresh token is dead.
+            APIError: If the server refuses the request for another reason.
+            CTraderConnectionTimeoutError: If the request times out.
+        """
+        request = ProtoOARefreshTokenReq(refresh_token=credentials.refresh_token)
+        try:
+            response = await self._protocol.request(request, ProtoOARefreshTokenRes, timeout=timeout)
+        except APIError as e:
+            if e.is_token_failure():
+                raise TokenExpiredError(credentials.account_id) from e
+            raise
+
+        rotated = credentials.with_refreshed_tokens(
+            access_token=response.access_token,
+            refresh_token=response.refresh_token,
+            expires_in=response.expires_in,
+        )
+        self.replace_credentials(rotated)
+
+        if self._token_store is not None:
+            await self._token_store.save(rotated)
+
+        logger.debug("Token refreshed for account %d, new expiry in %ds", credentials.account_id, response.expires_in)
+        return rotated
+
     async def probe_session(self, account_id: int, timeout: float | None = None) -> bool:
         """Return whether the account still holds a live session on this link.
 

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/src/ctrader_api_client/composition.py

@@ -91,16 +91,15 @@ def build_graph(
         client_id=config.client_id,
         client_secret=config.client_secret,
         restorer=market_data,
+        token_store=token_store,
     )
 
     maintainer = SessionMaintainer(
-        protocol=protocol,
         manager=auth,
         publisher=emitter,
         refresh_policy=config.refresh_policy,
         reauth_policy=config.reauth_policy,
         clock=clock,
-        token_store=token_store,
     )
 
     router = EventRouter(

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/src/ctrader_api_client/exceptions.py

@@ -151,11 +151,11 @@ class AccountAuthError(AuthenticationError):
 
 
 class TokenExpiredError(AuthenticationError):
-    """Access token has expired."""
+    """The server refused the access token, or the refresh token that was to replace it."""
 
     def __init__(self, ctid_trader_account_id: int | None = None) -> None:
         self.ctid_trader_account_id = ctid_trader_account_id
-        message = "Access token has expired"
+        message = "Token refused by the server"
         if ctid_trader_account_id:
             message += f" for account {ctid_trader_account_id}"
         super().__init__(message)

{ctrader_api_client-0.10.0 → ctrader_api_client-0.11.0}/tests/behavior/auth/conftest.py

@@ -13,7 +13,7 @@ from ctrader_api_client.auth import (
     SessionMaintainer,
 )
 
-from ...harness import ManualClock, RecordingPublisher, StubProtocol
+from ...harness import ManualClock, RecordingPublisher, RecordingStore, StubProtocol
 
 
 @pytest.fixture
@@ -22,18 +22,26 @@ def publisher() -> RecordingPublisher:
     return RecordingPublisher()
 
 
+@pytest.fixture
+def store() -> RecordingStore:
+    """Records every pair the manager under test persists."""
+    return RecordingStore()
+
+
 @pytest.fixture
 def make_auth(
     protocol: StubProtocol,
     publisher: RecordingPublisher,
+    store: RecordingStore,
 ) -> Callable[..., AuthManager]:
-    """Build auth managers."""
+    """Build auth managers that persist through the recording store."""
 
     def factory(**overrides: object) -> AuthManager:
         settings: dict[str, object] = {
             "publisher": publisher,
             "client_id": "test-client-id",
             "client_secret": "test-client-secret",
+            "token_store": store,
         }
         settings.update(overrides)
         return AuthManager(protocol=protocol, **settings)  # type: ignore[arg-type]
@@ -49,13 +57,15 @@ def auth(make_auth: Callable[..., AuthManager]) -> AuthManager:
 
 @pytest.fixture
 def make_maintainer(
-    protocol: StubProtocol,
     clock: ManualClock,
     publisher: RecordingPublisher,
     auth: AuthManager,
     serving: Callable[[SessionMaintainer], None],
 ) -> Callable[..., SessionMaintainer]:
-    """Build maintainers over the auth manager, with their loops already running.
+    """Build maintainers over an auth manager, with their loops already running.
+
+    The default manager is the `auth` fixture. A test that builds its own
+    manager, for example over a store that fails, passes it as `manager`.
 
     Every wait runs on the injected clock. The refresh retry wait is zero
     unless a test needs the retry to park, and the check interval stays
@@ -66,11 +76,10 @@ def make_maintainer(
         check_interval: float = 60.0,
         retry_wait: float = 0.0,
         reauth_policy: ReauthPolicy | None = None,
-        **overrides: object,
+        manager: AuthManager | None = None,
     ) -> SessionMaintainer:
         maintainer = SessionMaintainer(
-            protocol=protocol,
-            manager=auth,
+            manager=manager if manager is not None else auth,
             publisher=publisher,
             refresh_policy=RefreshPolicy(
                 check_interval=check_interval,
@@ -79,7 +88,6 @@ def make_maintainer(
             ),
             reauth_policy=reauth_policy if reauth_policy is not None else ReauthPolicy(min_wait=0.001, max_wait=0.01),
             clock=clock,
-            **overrides,  # type: ignore[arg-type]
         )
         serving(maintainer)
         return maintainer