use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
use crate::auth::Session;
use crate::error::StorageError;
use super::CredentialStore;
pub const SERVICE_NAME: &str = "eero-api";
pub const ACCOUNT_NAME: &str = "auth-tokens";
const BACKEND_NAME: &str = "keyring";
const UNPERSISTED_WARNING: &str = "Keyring did not retain the session; credentials are not \
persisted and will be lost when this process exits";
const UNCLEARED_WARNING: &str = "Keyring could not be cleared; a stored session may remain in it";
#[derive(Clone)]
pub struct KeyringStore {
service: String,
account: String,
warn_on_unpersisted: bool,
op_lock: Arc<Mutex<()>>,
}
impl std::fmt::Debug for KeyringStore {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("KeyringStore")
.field("service", &self.service)
.field("account", &self.account)
.field("warn_on_unpersisted", &self.warn_on_unpersisted)
.finish_non_exhaustive()
}
}
impl KeyringStore {
#[must_use]
pub fn new() -> Self {
Self::with_entry(SERVICE_NAME, ACCOUNT_NAME)
}
#[must_use]
pub fn with_entry(service: impl Into<String>, account: impl Into<String>) -> Self {
Self {
service: service.into(),
account: account.into(),
warn_on_unpersisted: true,
op_lock: Arc::new(Mutex::new(())),
}
}
#[must_use]
pub fn warn_on_unpersisted(mut self, warn: bool) -> Self {
self.warn_on_unpersisted = warn;
self
}
fn entry(&self) -> Result<keyring::Entry, StorageError> {
keyring::Entry::new(&self.service, &self.account).map_err(|err| backend_error(&err))
}
fn lock_operations(&self) -> MutexGuard<'_, ()> {
self.op_lock.lock().unwrap_or_else(PoisonError::into_inner)
}
fn load_unlocked(&self) -> Result<Session, StorageError> {
let entry = self.entry()?;
match entry.get_password() {
Ok(json) => {
let (session, migrated) = Session::from_json_migrating(&json)?;
if migrated {
super::migrate_and_verify(&session, BACKEND_NAME, |migrated| {
self.save_unlocked(migrated)
});
}
Ok(session)
}
Err(keyring::Error::NoEntry) => Ok(Session::empty()),
Err(err) => Err(backend_error(&err)),
}
}
fn save_unlocked(&self, session: &Session) -> Result<(), StorageError> {
let outcome = self.write_and_read_back(session);
match &outcome {
Ok(()) => tracing::debug!("Saved authentication data to keyring"),
Err(err) => self.report_unpersisted(err),
}
outcome
}
fn write_and_read_back(&self, session: &Session) -> Result<(), StorageError> {
let entry = self.entry()?;
let json = session.to_json()?;
entry
.set_password(&json)
.map_err(|err| backend_error(&err))?;
check_readback(self.entry()?.get_password(), session)
}
fn report_unpersisted(&self, err: &StorageError) {
match err {
StorageError::NotRetained { .. } => {}
StorageError::Backend { message, .. } => {
tracing::debug!("Error saving to keyring: {message}");
}
other => tracing::debug!("Error saving to keyring: {other}"),
}
if self.warn_on_unpersisted {
tracing::warn!("{UNPERSISTED_WARNING}");
}
}
fn clear_unlocked(&self) -> Result<(), StorageError> {
let outcome = self.delete_entry();
if let Err(err) = &outcome {
match err {
StorageError::Backend { message, .. } => {
tracing::debug!("Error clearing keyring: {message}");
}
other => tracing::debug!("Error clearing keyring: {other}"),
}
if self.warn_on_unpersisted {
tracing::warn!("{UNCLEARED_WARNING}");
}
}
outcome
}
fn delete_entry(&self) -> Result<(), StorageError> {
let entry = self.entry()?;
match entry.delete_credential() {
Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
Err(err) => Err(backend_error(&err)),
}
}
}
impl Default for KeyringStore {
fn default() -> Self {
Self::new()
}
}
impl CredentialStore for KeyringStore {
fn load(&self) -> Result<Session, StorageError> {
let _guard = self.lock_operations();
self.load_unlocked()
}
fn save(&self, session: &Session) -> Result<(), StorageError> {
let _guard = self.lock_operations();
self.save_unlocked(session)
}
fn clear(&self) -> Result<(), StorageError> {
let _guard = self.lock_operations();
self.clear_unlocked()
}
fn reports_failures(&self) -> bool {
self.warn_on_unpersisted
}
}
fn check_readback(
readback: Result<String, keyring::Error>,
saved: &Session,
) -> Result<(), StorageError> {
match readback {
Ok(json) => match Session::from_json(&json) {
Ok(stored) if stored.expose_token() == saved.expose_token() => Ok(()),
Ok(_) | Err(_) => Err(not_retained()),
},
Err(keyring::Error::NoEntry) => Err(not_retained()),
Err(err) => Err(backend_error(&err)),
}
}
fn not_retained() -> StorageError {
StorageError::NotRetained {
backend: BACKEND_NAME.to_owned(),
}
}
fn backend_error(err: &keyring::Error) -> StorageError {
StorageError::Backend {
backend: BACKEND_NAME.to_owned(),
message: err.to_string(),
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use std::sync::mpsc;
use std::time::Duration;
use tracing::Level;
#[cfg(target_os = "linux")]
use super::UNCLEARED_WARNING;
use super::{
ACCOUNT_NAME, BACKEND_NAME, CredentialStore, KeyringStore, SERVICE_NAME,
UNPERSISTED_WARNING, check_readback,
};
use crate::auth::Session;
use crate::error::StorageError;
use crate::storage::test_support::capture_logs;
#[test]
fn service_and_account_match_the_shared_eero_api_entry() {
assert_eq!(SERVICE_NAME, "eero-api");
assert_eq!(ACCOUNT_NAME, "auth-tokens");
}
#[test]
fn new_uses_the_shared_service_and_account() {
let store = KeyringStore::new();
assert_eq!(store.service, SERVICE_NAME);
assert_eq!(store.account, ACCOUNT_NAME);
}
#[test]
fn default_is_equivalent_to_new() {
let store = KeyringStore::default();
assert_eq!(store.service, SERVICE_NAME);
assert_eq!(store.account, ACCOUNT_NAME);
}
#[test]
fn with_entry_uses_the_given_service_and_account() {
let store = KeyringStore::with_entry("custom-service", "custom-account");
assert_eq!(store.service, "custom-service");
assert_eq!(store.account, "custom-account");
}
#[test]
fn debug_output_contains_no_credential() {
let store = KeyringStore::with_entry("svc", "acct");
let debug = format!("{store:?}");
assert!(debug.contains("svc"));
assert!(debug.contains("acct"));
}
#[test]
fn load_never_panics_and_never_fabricates_a_valid_session() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-load_never_panics_and_never_fabricates_a_valid_session",
);
match store.load() {
Ok(session) => assert!(!session.is_valid()),
Err(StorageError::Backend { backend, message }) => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.is_empty());
}
Err(other) => panic!("unexpected error variant: {other:?}"),
}
}
#[cfg(target_os = "linux")]
#[test]
fn load_without_a_dbus_session_bus_fails_cleanly_with_no_credential_in_the_message() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-load_without_a_dbus_session_bus_fails_cleanly_with_no_credential_in_the_message",
);
match store.load() {
Err(StorageError::Backend { backend, message }) => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.is_empty());
}
other => panic!(
"expected StorageError::Backend on Linux with no D-Bus session bus, got {other:?}"
),
}
}
struct ClearEntryOnDrop<'a>(&'a KeyringStore);
impl Drop for ClearEntryOnDrop<'_> {
fn drop(&mut self) {
let _ = self.0.clear();
}
}
#[test]
fn save_never_leaves_a_credential_behind_on_any_platform() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-save_never_leaves_a_credential_behind_on_any_platform",
);
let _cleanup = ClearEntryOnDrop(&store);
let session = Session::from_token("should-never-appear-in-any-error-message");
match store.save(&session) {
Ok(()) => {}
Err(StorageError::Backend { backend, message }) => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.contains("should-never-appear-in-any-error-message"));
}
Err(StorageError::NotRetained { backend }) => assert_eq!(backend, BACKEND_NAME),
Err(other) => panic!("unexpected error variant: {other:?}"),
}
}
#[cfg(target_os = "linux")]
#[test]
fn save_without_a_dbus_session_bus_fails_cleanly_with_no_credential_in_the_message() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-save_without_a_dbus_session_bus_fails_cleanly_with_no_credential_in_the_message",
);
let session = Session::from_token("should-never-appear-in-any-error-message");
match store.save(&session) {
Err(StorageError::Backend { backend, message }) => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.contains("should-never-appear-in-any-error-message"));
}
other => panic!(
"expected StorageError::Backend on Linux with no D-Bus session bus, got {other:?}"
),
}
}
#[test]
fn clear_without_a_working_backend_fails_cleanly_or_is_a_no_op() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-clear_without_a_working_backend_fails_cleanly_or_is_a_no_op",
);
match store.clear() {
Ok(()) => {}
Err(StorageError::Backend { backend, message }) => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.is_empty());
}
Err(other) => panic!("unexpected error variant: {other:?}"),
}
}
#[test]
fn a_readback_with_no_entry_is_not_retained() {
let err = check_readback(Err(keyring::Error::NoEntry), &Session::from_token("tok"))
.expect_err("nothing was stored");
assert!(matches!(&err, StorageError::NotRetained { backend } if backend == BACKEND_NAME));
}
#[test]
fn a_readback_with_another_token_is_not_retained() {
let stored = r#"{"session_id":"other","schema_version":2}"#.to_owned();
let err = check_readback(Ok(stored), &Session::from_token("tok"))
.expect_err("another token was stored");
assert!(matches!(err, StorageError::NotRetained { .. }));
}
#[test]
fn a_readback_with_the_same_token_is_retained() {
let saved = Session::from_token("tok");
let stored = saved.to_json().expect("serializes");
check_readback(Ok(stored), &saved).expect("the same token was stored");
}
#[test]
fn a_readback_with_a_legacy_record_of_the_same_token_is_retained() {
let stored = r#"{"user_token":"tok"}"#.to_owned();
check_readback(Ok(stored), &Session::from_token("tok"))
.expect("a legacy record is parsed like a load would parse it");
}
#[test]
fn a_readback_that_does_not_parse_is_not_retained() {
for garbage in ["not json", "", "[]", "\"tok\"", "null"] {
let err = check_readback(Ok(garbage.to_owned()), &Session::from_token("tok"))
.expect_err("not a credential record");
assert!(
matches!(err, StorageError::NotRetained { .. }),
"{garbage:?} -> {err:?}"
);
}
}
#[test]
fn any_other_readback_failure_stays_a_backend_error() {
let failure = keyring::Error::Invalid("service".to_owned(), "too short".to_owned());
let err = check_readback(Err(failure), &Session::from_token("tok"))
.expect_err("the keyring itself failed");
match err {
StorageError::Backend { backend, message } => {
assert_eq!(backend, BACKEND_NAME);
assert!(!message.is_empty());
}
other => panic!("expected a backend error, got {other:?}"),
}
}
#[test]
fn new_with_entry_and_default_warn_on_unpersisted() {
assert!(KeyringStore::new().warn_on_unpersisted);
assert!(KeyringStore::with_entry("svc", "acct").warn_on_unpersisted);
assert!(KeyringStore::default().warn_on_unpersisted);
}
#[test]
fn the_builder_turns_the_warning_off_and_back_on() {
let silenced = KeyringStore::with_entry("svc", "acct").warn_on_unpersisted(false);
assert!(!silenced.warn_on_unpersisted);
assert!(
!silenced.clone().warn_on_unpersisted,
"a clone keeps the setting"
);
assert!(silenced.warn_on_unpersisted(true).warn_on_unpersisted);
}
#[test]
fn debug_shows_the_warning_setting() {
assert!(format!("{:?}", KeyringStore::new()).contains("warn_on_unpersisted: true"));
let silenced = KeyringStore::new().warn_on_unpersisted(false);
assert!(format!("{silenced:?}").contains("warn_on_unpersisted: false"));
}
#[test]
fn a_save_that_was_not_retained_logs_exactly_one_fixed_warning() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry("svc", "acct");
store.report_unpersisted(&StorageError::NotRetained {
backend: BACKEND_NAME.to_owned(),
});
assert_eq!(
logs.messages(Level::WARN),
vec![UNPERSISTED_WARNING.to_owned()]
);
assert_eq!(
UNPERSISTED_WARNING,
"Keyring did not retain the session; credentials are not persisted and will be lost \
when this process exits"
);
assert!(
logs.messages(Level::DEBUG).is_empty(),
"a read-back that found nothing has no cause to report"
);
}
#[test]
fn a_rejected_save_logs_its_cause_at_debug_and_one_fixed_warning() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry("svc", "acct");
store.report_unpersisted(&StorageError::Backend {
backend: BACKEND_NAME.to_owned(),
message: "no secret service".to_owned(),
});
assert_eq!(
logs.messages(Level::DEBUG),
vec!["Error saving to keyring: no secret service".to_owned()]
);
assert_eq!(
logs.messages(Level::WARN),
vec![UNPERSISTED_WARNING.to_owned()]
);
}
#[test]
fn a_silenced_store_logs_the_cause_at_debug_and_no_warning() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry("svc", "acct").warn_on_unpersisted(false);
store.report_unpersisted(&StorageError::Backend {
backend: BACKEND_NAME.to_owned(),
message: "no secret service".to_owned(),
});
store.report_unpersisted(&StorageError::NotRetained {
backend: BACKEND_NAME.to_owned(),
});
assert!(logs.messages(Level::WARN).is_empty());
assert_eq!(logs.count(Level::DEBUG, "Error saving to keyring"), 1);
}
#[cfg(target_os = "linux")]
#[test]
fn a_save_without_a_dbus_session_bus_warns_exactly_once_without_the_token() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-a_save_without_a_dbus_session_bus_warns_exactly_once_without_the_token",
);
let err = store
.save(&Session::from_token("secret_token"))
.expect_err("no keyring is reachable");
assert!(matches!(err, StorageError::Backend { .. }), "got {err:?}");
assert_eq!(
logs.count(Level::WARN, "Keyring did not retain the session"),
1,
"{:?}",
logs.messages(Level::WARN)
);
assert_eq!(logs.messages(Level::WARN).len(), 1);
assert_eq!(logs.count(Level::DEBUG, "Error saving to keyring"), 1);
assert!(!logs.mentions("secret_token"));
}
#[cfg(target_os = "linux")]
#[test]
fn a_clear_without_a_dbus_session_bus_warns_exactly_once() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-a_clear_without_a_dbus_session_bus_warns_exactly_once",
);
let err = store.clear().expect_err("no keyring is reachable");
assert!(matches!(err, StorageError::Backend { .. }), "got {err:?}");
assert_eq!(
logs.messages(Level::WARN),
vec![UNCLEARED_WARNING.to_owned()]
);
assert_eq!(logs.count(Level::DEBUG, "Error clearing keyring"), 1);
}
#[cfg(target_os = "linux")]
#[test]
fn a_silenced_clear_without_a_dbus_session_bus_logs_only_the_cause() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-a_silenced_clear_without_a_dbus_session_bus_logs_only_the_cause",
)
.warn_on_unpersisted(false);
store.clear().expect_err("no keyring is reachable");
assert!(logs.messages(Level::WARN).is_empty());
assert_eq!(logs.count(Level::DEBUG, "Error clearing keyring"), 1);
}
#[test]
fn the_keyring_store_reports_its_failures_unless_silenced() {
assert!(KeyringStore::with_entry("svc", "acct").reports_failures());
assert!(
!KeyringStore::with_entry("svc", "acct")
.warn_on_unpersisted(false)
.reports_failures()
);
}
#[cfg(target_os = "linux")]
#[test]
fn a_silenced_save_without_a_dbus_session_bus_logs_only_the_cause() {
let (_guard, logs) = capture_logs();
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-a_silenced_save_without_a_dbus_session_bus_logs_only_the_cause",
)
.warn_on_unpersisted(false);
store
.save(&Session::from_token("secret_token"))
.expect_err("no keyring is reachable");
assert!(logs.messages(Level::WARN).is_empty());
assert_eq!(logs.count(Level::DEBUG, "Error saving to keyring"), 1);
assert!(!logs.mentions("secret_token"));
}
#[test]
fn clones_share_one_operation_lock_and_separate_stores_do_not() {
let store = KeyringStore::with_entry("svc", "acct");
let clone = store.clone();
let other = KeyringStore::with_entry("svc", "acct");
assert!(Arc::ptr_eq(&store.op_lock, &clone.op_lock));
assert!(!Arc::ptr_eq(&store.op_lock, &other.op_lock));
}
fn assert_waits_for_the_lock(
account: &str,
operation: impl FnOnce(&KeyringStore) + Send + 'static,
) {
let store = KeyringStore::with_entry("rusteero-test-service-no-backend", account);
let worker = store.clone();
let guard = store.lock_operations();
let (done_tx, done_rx) = mpsc::channel();
let thread = std::thread::spawn(move || {
operation(&worker);
let _ = done_tx.send(());
});
assert!(
done_rx.recv_timeout(Duration::from_millis(50)).is_err(),
"the operation ran while the lock was held"
);
drop(guard);
done_rx
.recv_timeout(Duration::from_secs(5))
.expect("the operation completes once the lock is free");
thread.join().expect("the operation thread finishes");
}
#[test]
fn load_waits_for_the_operation_lock() {
assert_waits_for_the_lock("rusteero-test-account-no-backend-op-lock-load", |store| {
let _ = store.load();
});
}
#[test]
fn save_waits_for_the_operation_lock() {
assert_waits_for_the_lock("rusteero-test-account-no-backend-op-lock-save", |store| {
let _ = store.save(&Session::from_token("should-never-persist"));
let _ = store.clear();
});
}
#[test]
fn clear_waits_for_the_operation_lock() {
assert_waits_for_the_lock("rusteero-test-account-no-backend-op-lock-clear", |store| {
let _ = store.clear();
});
}
#[test]
fn a_panic_while_the_lock_is_held_does_not_wedge_the_store() {
let store = KeyringStore::with_entry(
"rusteero-test-service-no-backend",
"rusteero-test-account-no-backend-poisoned-lock",
);
let poisoner = store.clone();
let result = std::thread::spawn(move || {
let _guard = poisoner.lock_operations();
panic!("a store operation panicked");
})
.join();
assert!(result.is_err());
let _ = store.clear();
}
#[test]
#[ignore = "requires a real OS keyring backend (Secret Service/Keychain/Credential Manager)"]
fn keyring_round_trip_save_load_clear() {
let store = KeyringStore::with_entry("rusteero-test-service", "rusteero-test-account");
let session = Session::from_token("integration-test-token");
store
.save(&session)
.expect("save succeeds against a real backend");
let loaded = store.load().expect("load succeeds against a real backend");
assert!(loaded.is_valid());
store
.clear()
.expect("clear succeeds against a real backend");
let cleared = store.load().expect("load succeeds after clear");
assert!(!cleared.is_valid());
}
}