Skip to content

Credential Storage

github-actions[bot] edited this page Oct 17, 2026 · 8 revisions

๐Ÿ” Credential Storage

The CredentialStorage abstraction, its four concrete backends, and how create_storage() picks one.


๐Ÿ—๏ธ The CredentialStorage Abstraction

Every backend in src/eero/api/auth_storage.py implements the same abstract base class:

class CredentialStorage(ABC):
    async def load(self) -> AuthCredentials: ...
    async def save(self, credentials: AuthCredentials) -> bool: ...
    async def clear(self) -> None: ...

AuthCredentials is a plain @dataclass with exactly one field โ€” session_id โ€” plus helpers to_dict(), from_dict(), and clear_all(). Every backend round-trips this object; none of them know about networks, profiles, or anything besides the session token. There is no expiry field and no refresh token: the server decides whether a token is still valid, and refreshing reuses the same token (see Authentication).

to_dict() produces the persisted record shape, which is the same for every backend:

{
  "session_id": "โ€ฆ",
  "schema_version": 2
}

schema_version is eero.const.CREDENTIAL_SCHEMA_VERSION. A stored record without that key is a legacy record from an earlier release โ€” it may use the pre-v3.0.0 user_token key instead of session_id, and may carry the extra fields 7.x wrote alongside the token (named in Migration). Each backend's load() migrates such a record in place: it keeps the token (reading session_id, falling back to user_token), drops every other field, and re-saves the record in the current shape. The migration runs once per backend, is idempotent (a record that already carries schema_version is never rewritten), and logs no values โ€” a DEBUG line that a migration happened, then a read-back check that logs DEBUG on match or WARNING on mismatch (the in-memory credentials are returned either way).

save() never raises and returns whether the backend now holds the saved token, judged by reading it back rather than by the write not raising (a write call that returns normally proves nothing: a no-op keyring accepts everything). Callers that ignore the return value keep working. A third-party backend written against the earlier -> None contract may still return None; AuthAPI treats that as "unknown, assume persisted" rather than as a failure. MemoryStorage returns True because it holds the record for the life of the process, not because it is durable.

AuthAPI owns exactly one CredentialStorage instance (built by create_storage() in its __init__) and calls load() on __aenter__, save() after verify() and set_session_token() (never after login(), whose pending token stays in memory until verification succeeds), and clear() from logout(), clear_session_token(), clear_auth_data() and a refresh that reports the session as terminated. AuthAPI records the outcome of each save and exposes it as the read-only property credentials_persisted (also on EeroAPI and EeroClient): False only when the last saved session was read back and no backend retained it, True otherwise (including after a load or a clear, and when login() installs a pending token, which is never saved). login() and verify() keep returning only the API outcome, so check this property when losing the session on exit matters.

There are four concrete implementations: KeyringStorage, FileStorage, MemoryStorage, ChainedStorage.

Threads, locking and cancellation

KeyringStorage and FileStorage do blocking work (keyring calls, open, fsync, os.replace), so they run each load(), save() and clear() on a worker thread with asyncio.to_thread instead of on the event loop. A slow keyring or disk stalls only that call, not the rest of your application (which matters for a long-running async host such as a web service during login or logout).

  • One thread hop per operation. The whole synchronous unit runs in the thread: for save() that includes the write and its read-back; for load() it includes a legacy-record migration and the migration's read-back. Behaviour, return values and log lines are unchanged.
  • Serialised per instance. Each instance holds an asyncio.Lock around every thread hop, so a save() and a clear() on the same backend cannot interleave: whichever you awaited first runs first, and the other waits. Separate instances (for example two FileStorage objects on the same path) are not coordinated with each other.
  • Cancellation does not stop a running thread. If the task awaiting an operation is cancelled while its thread is already running, the thread runs to completion. A save() still finishes its atomic os.replace(), so afterwards the file holds either the previous record or the new one, never a partial one; the cancelled caller simply never sees the result. The lock stays held until the thread finishes, so the next operation on that instance waits instead of racing it. An operation that is only waiting for the lock is cancelled outright and does no work.
  • The lock is per event loop. It is created on first use rather than in the constructor, so building a backend never binds it to a loop, and a backend reused from a later asyncio.run() gets a fresh lock for that loop.
  • MemoryStorage and ChainedStorage use no threads of their own: the memory backend does no I/O, and the chain just awaits its backends (so it inherits their serialisation).

๐Ÿงญ create_storage() โ€” Selection Logic

def create_storage(
    use_keyring: bool = True,
    cookie_file: Optional[str] = None,
) -> CredentialStorage:

This is the only place backend selection happens โ€” driven purely by the use_keyring / cookie_file values you pass into EeroClient(...) (which flow through EeroAPI โ†’ AuthAPI unchanged).

use_keyring cookie_file Backend returned
True set ChainedStorage(primary=KeyringStorage(), fallback=FileStorage(cookie_file))
True None KeyringStorage()
False set FileStorage(cookie_file)
False None MemoryStorage()

In prose: keyring is tried whenever use_keyring=True; a file path is only ever consulted as a fallback alongside keyring, or as the sole backend when you explicitly disable keyring; and if you disable keyring without giving a file path, there is nothing left to fall back to, so credentials live in memory only for the life of the process.


๐Ÿ”‘ KeyringStorage

class KeyringStorage(CredentialStorage):
    SERVICE_NAME = "eero-api"
    ACCOUNT_NAME = "auth-tokens"

Delegates to the third-party keyring package, which resolves a platform backend at import time:

OS Backend
๐ŸŽ macOS Keychain
๐Ÿง Linux Secret Service (GNOME Keyring, KWallet)
๐ŸชŸ Windows Windows Credential Locker

load() calls keyring.get_password(SERVICE_NAME, ACCOUNT_NAME), JSON-decodes the result into an AuthCredentials, and โ€” if the stored record was a legacy one (no schema_version key) โ€” re-saves it in the current shape before returning it. save() JSON-encodes credentials.to_dict(), calls keyring.set_password(...), then reads the entry back with keyring.get_password(...) and returns True only if the stored session_id matches. clear() calls keyring.delete_password(...), swallowing keyring.errors.PasswordDeleteError silently (nothing to delete is not an error) and logging any other exception at DEBUG; clear() never raises. Every keyring call happens on a worker thread (see Threads, locking and cancellation).

Note: load() and save() wrap the underlying keyring calls in a bare except Exception, so a locked keyring, a missing Secret Service daemon on headless Linux, or any other backend failure is non-fatal: load() returns an empty AuthCredentials() and save() returns False, never raising. A backend that reports success without persisting anything (e.g. keyring.backends.null.Keyring) is caught the same way, by the read-back.

โš ๏ธ Warning: With the default EeroClient() (use_keyring=True, no cookie_file) the keyring is the only backend. If it retains nothing, login()/verify() still succeed and the session works for this process, but it is not persisted anywhere and is lost on exit. save() logs a fixed WARNING ("Keyring did not retain the session; credentials are not persisted and will be lost when this process exits", never the token), and credentials_persisted is False. To fix it, give the client a cookie_file so there is a fallback, or use use_keyring=False, cookie_file=.... When create_storage() layers a file behind the keyring it builds KeyringStorage(warn_on_unpersisted=False): the keyring failing to retain a write is routine there and handled by the fallback, so that warning is suppressed (the keyring still returns False and logs the cause at DEBUG).


๐Ÿ“„ FileStorage

class FileStorage(CredentialStorage):
    def __init__(self, file_path: str) -> None
  • The path is resolved eagerly in __init__ via os.path.abspath(os.path.expanduser(file_path)) โ€” ~ is expanded and the result is made absolute. There is no default path; you must always supply one.
  • file_path is a read-only @property returning the resolved path.
  • load() returns an empty AuthCredentials() if the file doesn't exist or fails to parse as JSON (FileNotFoundError, json.JSONDecodeError caught explicitly; any other exception is caught too and logged at WARNING). A legacy record found on disk is migrated and re-saved, same as KeyringStorage.
  • save() creates the parent directory (os.makedirs(..., exist_ok=True)), refuses to write if file_path is a symlink, writes json.dumps(credentials.to_dict()) to a fresh tempfile.mkstemp() file in the same directory (created 0600), fsyncs it, re-asserts 0600 with os.chmod, then atomically swaps it into place with os.replace(). A crash mid-write leaves the previous file or nothing โ€” never a partial record. The file is then read back, and save() returns True only if the stored token matches (a mismatch logs a fixed WARNING). Any failure is logged at ERROR and swallowed, returning False; save() never raises. The exact keys written are:
{
  "session_id": "โ€ฆ",
  "schema_version": 2
}

Note: If your own tooling reads this file, read session_id only. The extra fields 7.x wrote are no longer written, and any copy of them still sitting in an old file is dropped the first time the SDK loads it โ€” see Migration.

  • Every step above, including the read-back, runs on one worker thread under the instance lock (see Threads, locking and cancellation). Cancelling a save() mid-flight cannot leave a half-written file: the temporary file is swapped in atomically or removed, so the destination holds the old record or the new one, still 0600.
  • clear() removes the file with os.remove() if it exists (a missing file is a silent no-op); a removal error is logged at WARNING and swallowed (never raises).

โ›“๏ธ ChainedStorage

class ChainedStorage(CredentialStorage):
    def __init__(self, primary: CredentialStorage, fallback: CredentialStorage) -> None

Only ever constructed by create_storage() as ChainedStorage(primary=KeyringStorage(), fallback=FileStorage(cookie_file)) โ€” but nothing stops you from composing it yourself with any two CredentialStorage instances. ChainedStorage performs no legacy-record migration of its own; each underlying backend migrates on its own load().

Operation Order of operations On partial failure
load() Try primary.load() first. If it returns credentials with a session_id, return them immediately. Otherwise try fallback.load(). If the fallback holds a session_id, it is promoted with primary.save(credentials); the primary is then re-loaded and, if the read-back matches, fallback.clear() deletes the fallback copy so only one backend holds the live record. If the read-back does not match, the fallback copy is kept (DEBUG log).
save() Try primary.save(). If it does not raise, read the primary back with primary.load() and compare session_id to what was just saved. If primary.save() raises, or the read-back doesn't match what was saved, fallback.save() is attempted (both cases are logged at DEBUG) and the fallback is read back too. If both the primary path and fallback.save() fail, the fallback's exception is logged at ERROR and swallowed โ€” save() never raises to the caller. Returns True if either backend was read back holding the token. A verified primary write does not write the fallback, and instead retires the fallback record (best effort; a failing clear is logged at DEBUG and ignored), so a superseded token cannot be resurrected by load()'s promotion if the primary is wiped later. The fallback is read back first and cleared only if it still holds a record this instance superseded: the token it last loaded from, promoted out of, or wrote to the fallback, or the token just saved. A different session found there (another process sharing the cookie file, with no working keyring) is left in place and logged at DEBUG.
clear() Attempts primary.clear() and fallback.clear() independently; one raising never skips the other. A backend that raises is logged at WARNING (fixed text) and ignored. clear() raises only if both backends raised, and then re-raises the first error after both were attempted. logout(), clear_session_token() and clear_auth_data() therefore never raise because of a single failing backend; the in-memory token is cleared first in any case.

โ„น๏ธ Note: save() verifies the primary write with a read-back before skipping the file fallback. KeyringStorage.save() catches its own exceptions internally and returns normally instead of raising (see above), and some keyring backends (e.g. keyring.backends.null.Keyring) report success without persisting anything at all โ€” no exception, ever. Relying on primary.save() raising would miss both cases, so ChainedStorage.save() instead mirrors the read-back-then-act pattern load()'s own promotion logic already uses: after a primary write that didn't raise, it re-load()s the primary and compares session_id against what it just wrote. Only a matching read-back skips the fallback; any mismatch โ€” raised exception or silent no-op alike โ€” falls through to fallback.save(), so ChainedStorage (use_keyring=True with a cookie_file set) is a viable choice for headless/CI/container persistence. use_keyring=False, cookie_file=... (plain FileStorage) remains valid too, and is simpler if you have no use for the keyring at all.


๐Ÿง  MemoryStorage

class MemoryStorage(CredentialStorage):
    def __init__(self) -> None

Holds one AuthCredentials instance as a plain attribute. load() returns a copy and save() stores a copy, so mutating the live credentials object in place cannot change the stored record without going through save()/clear(); clear() resets the attribute. No I/O, no serialization, nothing ever touches disk.

โš ๏ธ Warning: This is the silent-data-loss backend. EeroClient(use_keyring=False) with no cookie_file resolves here automatically (see the selection table above) โ€” there is no error, warning, or log line telling you this happened. Every session, once the process exits, is gone. Only use this deliberately (tests, short-lived ephemeral processes, secrets injected fresh every run via set_session_token()).


๐Ÿ—‚๏ธ Choosing a Backend

Deployment scenario Recommended construction Why
๐Ÿ–ฅ๏ธ Desktop (macOS/Windows/Linux w/ desktop env) EeroClient() (defaults) KeyringStorage alone โ€” OS-encrypted, no file to protect
๐Ÿง Headless Linux (no Secret Service daemon) EeroClient(use_keyring=False, cookie_file="/path/to/creds.json") A keyring-only setup retains nothing here (save() warns and credentials_persisted is False); with a cookie_file, ChainedStorage's read-back catches that and falls through to the file (see note above), but there's no keyring to gain anything from here anyway โ€” skip it entirely and go straight to FileStorage
๐Ÿณ Docker container EeroClient(use_keyring=False, cookie_file="/data/eero-cookies.json") No keyring daemon available inside most containers; skip straight to FileStorage and mount /data as a volume for persistence across restarts
๐Ÿค– CI pipeline EeroClient(use_keyring=False, cookie_file=<workspace path>) + set_session_token() from a CI secret No interactive OTP possible; seed the token directly each run (see Authentication)
โ˜๏ธ Serverless / ephemeral (Lambda-style, no writable disk) EeroClient(use_keyring=False) Falls through to MemoryStorage deliberately โ€” nothing to persist between invocations anyway; re-seed via set_session_token() on every cold start

๐Ÿ”Œ Custom Backends

The source does not expose an injection point on EeroClient, EeroAPI, or AuthAPI for supplying your own CredentialStorage implementation โ€” AuthAPI.__init__ always calls create_storage(use_keyring, cookie_file) internally, and that function only ever returns one of the four built-in classes. If you need different storage behavior (e.g. a secrets-manager-backed store), your options are:

  • Subclass CredentialStorage yourself and manage it entirely outside this SDK, using set_session_token() / clear_session_token() on EeroClient to move data in and out of AuthAPI at the times that matter to you.
  • Use cookie_file pointed at a path your own tooling manages (e.g. a file synced from a secrets manager before the process starts).

There is no monkey-patch-free extension point beyond that โ€” don't assume one exists.


๐Ÿ”„ Rotating / Clearing Credentials

Goal Call
Rotate to a new externally-issued token await client.set_session_token(new_token)
Drop the active session locally, no server round-trip await client.clear_session_token()
Log out and tell the server too await client.logout()
Same as clear_session_token() plus resets the login-in-progress flag, the preferred network and the in-memory cache await client.clear_auth_data() (since v8.4.0)

Every credential-dropping call above (clear_session_token, logout, clear_auth_data) deletes the stored record from every backend โ€” there is no "re-save an empty record" variant. The operations exposed on EeroClient also invalidate its in-memory response cache as a side effect (set_session_token, clear_session_token and clear_auth_data always; logout when it returns True, i.e. whenever credentials were actually present), so a rotated or cleared session never serves stale cached data.


๐Ÿ”— Related Pages

  • Home โ€” Overview and quick start
  • Configuration โ€” Storage-selection summary table and constructor options
  • Authentication โ€” Login/verify flow, session transport, and what gets persisted
  • Migration โ€” What changed in the credential record in v8.0.0
  • Logging and Security โ€” Sensitive-field redaction in logs
  • Troubleshooting โ€” Common issues & fixes

Clone this wiki locally