pub struct FileStore { /* private fields */ }Expand description
A CredentialStore backed by a single JSON file on disk.
Mirrors FileStorage (auth_storage.py:425-606): the file holds exactly the JSON object
Session::to_json/Session::from_json produce/consume (session_id, schema_version,
plus the legacy user_token read alias) — the same shape a Python eero-api install reads
and writes, so the two libraries can share one cookie file. There is deliberately no default
path: like FileStorage.__init__, which always requires an explicit file_path, choosing
where the file lives is left entirely to the caller (in eero-api’s ecosystem, that
choice belongs to the CLI layer, not this library).
§Verified saves
FileStore::save reads the file back after the atomic rename and parses it like a load
would; it returns Ok(()) only if the stored token is the one that was saved. If the file is
missing, unparseable or holds another token (the destination was swapped or overwritten
between the rename and the read-back), it logs a fixed WARN — Credential file did not retain the saved session, never the token — and returns StorageError::NotRetained
(auth_storage.py:582-586).
§Concurrency
Every load, save and clear on one FileStore runs under an internal lock held for the
whole operation (the read-back and a legacy-record migration included), so a save and a
clear cannot interleave: call order decides the outcome, and a clear can no longer remove a
concurrent save’s temporary file. Two FileStore values on the same path are not
coordinated with each other, exactly as in eero-api (auth_storage.py:190-235).
§Security: atomic 0600 creation, not chmod after the fact
Python’s FileStorage.save() creates the temporary file with tempfile.mkstemp (mode 0600)
and re-asserts 0600 with a trailing os.chmod() as defense in depth
(auth_storage.py:555-569). This port needs no such second step: FileStore::save writes
to a temporary file in the same directory, created with 0600 permissions atomically as
part of the file-creation syscall (via std::os::unix::fs::OpenOptionsExt::mode), then
renames it into place. A crash between the write and the rename leaves either the old file or
nothing at all — never a partially-written or loosely-permissioned target file.
This guarantee is Unix-only. OpenOptionsExt::mode has no equivalent in the Windows
standard library; on non-Unix platforms the temporary file is created with whatever default
permissions/ACL the OS applies, and this crate does not attempt to further restrict them.
Callers on Windows should not rely on the stored file being owner-only — treat the containing
directory’s own ACLs as the real access boundary there.
§Security: writing through a symlink at the final path
Python’s FileStorage.save() refuses to write when the final path is a symlink
(os.path.islink check before opening the temp file, auth_storage.py:548-551) — a defence
against a symlink planted at the cookie-file path being used to redirect a credential write
onto an attacker-chosen target. This port does not reproduce that check as a separate
precondition, and does not need to: the final step of FileStore::save is fs::rename,
not an in-place open of path. POSIX rename(2) (and its Windows equivalent) replaces
whatever is at the destination — including a symlink — rather than following it, so the write
always lands at path itself, never at whatever a symlink there might point to. This is
verified by save_replaces_a_symlink_at_the_destination_rather_than_following_it below rather
than merely asserted in this comment.
§Security: no orphaned plaintext credential
The temporary file above is given a name that is unique for the lifetime of this process
(see unique_temp_path), and every error path in the create/write/sync/rename sequence
removes it before returning (see write_private_atomically) — a crash between those
steps is the only way a temp file can survive, and FileStore::clear proactively removes
any such orphan for path (see remove_orphaned_temp_files), so a stale, fully-valid
plaintext credential can never outlive an explicit clear() call.
Implementations§
Source§impl FileStore
impl FileStore
Sourcepub fn new(path: impl Into<PathBuf>) -> Self
pub fn new(path: impl Into<PathBuf>) -> Self
Creates a store backed by path, which need not exist yet.
Unlike FileStorage.__init__ (auth_storage.py:432-440), which eagerly expands ~ and
absolutizes the path at construction time, path is stored exactly as given — this port
has no path-expansion dependency available and resolving ~/relative paths is left to
the caller, consistent with there being no default path anywhere in this crate.
Trait Implementations§
Source§impl CredentialStore for FileStore
impl CredentialStore for FileStore
Source§fn reports_failures(&self) -> bool
fn reports_failures(&self) -> bool
true: a failed save is logged at ERROR (or, for a record that was not retained, at
WARN) and a failed clear at WARN, with eero-api’s texts.