pub mod chained;
pub mod file;
#[cfg(feature = "keyring")]
pub mod keyring;
pub mod memory;
pub use crate::error::StorageError;
pub use chained::ChainedStore;
pub use file::FileStore;
#[cfg(feature = "keyring")]
pub use keyring::KeyringStore;
pub use memory::MemoryStore;
use std::path::PathBuf;
use std::sync::Arc;
use crate::auth::Session;
pub(crate) fn migrate_and_verify<S: CredentialStore + ?Sized>(
store: &S,
session: &Session,
backend: &str,
) {
if store.save(session).is_err() {
tracing::warn!(
"Migration read-back did not match for {backend} storage; in-memory credentials \
are still returned to the caller"
);
return;
}
match store.load() {
Ok(reloaded) if reloaded.expose_token() == session.expose_token() => {
tracing::debug!("Migration read-back verified for {backend} storage");
}
_ => {
tracing::warn!(
"Migration read-back did not match for {backend} storage; in-memory credentials \
are still returned to the caller"
);
}
}
}
pub trait CredentialStore: Send + Sync + std::fmt::Debug {
fn load(&self) -> Result<Session, StorageError>;
fn save(&self, session: &Session) -> Result<(), StorageError>;
fn clear(&self) -> Result<(), StorageError>;
}
fn join_error_to_storage_error(join_err: &tokio::task::JoinError) -> StorageError {
StorageError::Backend {
backend: "credential-store-task".to_owned(),
message: format!(
"blocking credential-store task {} failed: panicked={}, cancelled={}",
join_err.id(),
join_err.is_panic(),
join_err.is_cancelled()
),
}
}
#[allow(dead_code)]
pub(crate) async fn load_async(store: Arc<dyn CredentialStore>) -> Result<Session, StorageError> {
match tokio::task::spawn_blocking(move || store.load()).await {
Ok(result) => result,
Err(join_err) => Err(join_error_to_storage_error(&join_err)),
}
}
#[allow(dead_code)]
pub(crate) async fn save_async(
store: Arc<dyn CredentialStore>,
session: Session,
) -> Result<(), StorageError> {
match tokio::task::spawn_blocking(move || store.save(&session)).await {
Ok(result) => result,
Err(join_err) => Err(join_error_to_storage_error(&join_err)),
}
}
#[allow(dead_code)]
pub(crate) async fn clear_async(store: Arc<dyn CredentialStore>) -> Result<(), StorageError> {
match tokio::task::spawn_blocking(move || store.clear()).await {
Ok(result) => result,
Err(join_err) => Err(join_error_to_storage_error(&join_err)),
}
}
#[derive(Debug, Clone, Default)]
pub struct StorageConfig {
pub use_keyring: bool,
pub cookie_file: Option<PathBuf>,
}
impl StorageConfig {
#[must_use]
pub fn new() -> Self {
Self::default()
}
}
#[cfg(feature = "keyring")]
#[must_use]
pub fn create_storage(config: &StorageConfig) -> Arc<dyn CredentialStore> {
match (config.use_keyring, &config.cookie_file) {
(true, Some(path)) => Arc::new(ChainedStore::new(
Arc::new(KeyringStore::new()),
Arc::new(FileStore::new(path.clone())),
)),
(true, None) => Arc::new(KeyringStore::new()),
(false, Some(path)) => Arc::new(FileStore::new(path.clone())),
(false, None) => Arc::new(MemoryStore::new()),
}
}
#[cfg(not(feature = "keyring"))]
#[must_use]
pub fn create_storage(config: &StorageConfig) -> Arc<dyn CredentialStore> {
match &config.cookie_file {
Some(path) => Arc::new(FileStore::new(path.clone())),
None => Arc::new(MemoryStore::new()),
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use super::{
CredentialStore, StorageConfig, StorageError, clear_async, create_storage, load_async,
save_async,
};
use crate::auth::Session;
#[test]
fn storage_config_default_and_new_are_both_off() {
let default = StorageConfig::default();
assert!(!default.use_keyring);
assert!(default.cookie_file.is_none());
let via_new = StorageConfig::new();
assert!(!via_new.use_keyring);
assert!(via_new.cookie_file.is_none());
}
#[cfg(feature = "keyring")]
mod keyring_feature_matrix {
use std::path::PathBuf;
use super::{Session, StorageConfig, create_storage};
#[test]
fn neither_yields_a_working_memory_store() {
let store = create_storage(&StorageConfig::default());
assert!(format!("{store:?}").contains("MemoryStore"));
store
.save(&Session::from_token("tok"))
.expect("MemoryStore never fails");
assert_eq!(
store.load().expect("load never fails").expose_token(),
"tok"
);
}
#[test]
fn file_only_yields_a_working_file_store() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("cookies.json");
let store = create_storage(&StorageConfig {
use_keyring: false,
cookie_file: Some(path.clone()),
});
let debug = format!("{store:?}");
assert!(debug.contains("FileStore"));
assert!(!debug.contains("ChainedStore"));
store
.save(&Session::from_token("tok"))
.expect("file save succeeds");
assert!(path.exists());
assert_eq!(
store.load().expect("file load succeeds").expose_token(),
"tok"
);
}
#[test]
fn keyring_only_yields_a_bare_keyring_store_with_no_file_fallback() {
let store = create_storage(&StorageConfig {
use_keyring: true,
cookie_file: None,
});
let debug = format!("{store:?}");
assert!(debug.contains("KeyringStore"));
assert!(!debug.contains("ChainedStore"));
assert!(!debug.contains("FileStore"));
}
#[test]
fn both_yields_a_chained_store_of_keyring_primary_and_file_fallback() {
let store = create_storage(&StorageConfig {
use_keyring: true,
cookie_file: Some(PathBuf::from("/tmp/rusteero-test-does-not-touch-disk.json")),
});
let debug = format!("{store:?}");
assert!(debug.contains("ChainedStore"));
assert!(debug.contains("KeyringStore"));
assert!(debug.contains("FileStore"));
}
}
#[cfg(not(feature = "keyring"))]
mod no_keyring_feature_matrix {
use super::{Session, StorageConfig, create_storage};
#[test]
fn neither_yields_a_working_memory_store() {
let store = create_storage(&StorageConfig::default());
assert!(format!("{store:?}").contains("MemoryStore"));
store
.save(&Session::from_token("tok"))
.expect("MemoryStore never fails");
assert_eq!(
store.load().expect("load never fails").expose_token(),
"tok"
);
}
#[test]
fn file_only_yields_a_working_file_store() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("cookies.json");
let store = create_storage(&StorageConfig {
use_keyring: false,
cookie_file: Some(path.clone()),
});
store
.save(&Session::from_token("tok"))
.expect("file save succeeds");
assert!(path.exists());
}
#[test]
fn keyring_requested_with_no_file_degrades_to_a_working_memory_store() {
let store = create_storage(&StorageConfig {
use_keyring: true,
cookie_file: None,
});
assert!(format!("{store:?}").contains("MemoryStore"));
store
.save(&Session::from_token("tok"))
.expect("MemoryStore never fails");
assert_eq!(
store.load().expect("load never fails").expose_token(),
"tok"
);
}
#[test]
fn keyring_requested_with_a_file_degrades_to_a_working_file_store() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("cookies.json");
let store = create_storage(&StorageConfig {
use_keyring: true,
cookie_file: Some(path.clone()),
});
assert!(format!("{store:?}").contains("FileStore"));
store
.save(&Session::from_token("tok"))
.expect("file save succeeds");
assert!(path.exists());
}
}
#[tokio::test]
async fn save_load_clear_async_round_trip_through_a_shared_store() {
let store: Arc<dyn CredentialStore> = Arc::new(super::MemoryStore::new());
save_async(Arc::clone(&store), Session::from_token("tok-async"))
.await
.expect("save succeeds");
let loaded = load_async(Arc::clone(&store)).await.expect("load succeeds");
assert_eq!(loaded.expose_token(), "tok-async");
clear_async(Arc::clone(&store))
.await
.expect("clear succeeds");
assert!(!load_async(store).await.expect("load succeeds").is_valid());
}
#[derive(Debug, Default)]
struct AlwaysFailsStore;
impl CredentialStore for AlwaysFailsStore {
fn load(&self) -> Result<Session, StorageError> {
Err(StorageError::Backend {
backend: "always-fails".to_owned(),
message: "deliberate test failure".to_owned(),
})
}
fn save(&self, _session: &Session) -> Result<(), StorageError> {
Err(StorageError::Backend {
backend: "always-fails".to_owned(),
message: "deliberate test failure".to_owned(),
})
}
fn clear(&self) -> Result<(), StorageError> {
Err(StorageError::Backend {
backend: "always-fails".to_owned(),
message: "deliberate test failure".to_owned(),
})
}
}
#[tokio::test]
async fn save_async_propagates_the_stores_own_error_unchanged() {
let store: Arc<dyn CredentialStore> = Arc::new(AlwaysFailsStore);
let err = save_async(store, Session::from_token("tok"))
.await
.expect_err("the store always fails");
assert!(matches!(err, StorageError::Backend { backend, .. } if backend == "always-fails"));
}
#[derive(Debug, Default)]
struct PanickingStore;
impl CredentialStore for PanickingStore {
fn load(&self) -> Result<Session, StorageError> {
panic!("PanickingStore::load always panics");
}
fn save(&self, _session: &Session) -> Result<(), StorageError> {
panic!("PanickingStore::save always panics");
}
fn clear(&self) -> Result<(), StorageError> {
panic!("PanickingStore::clear always panics");
}
}
#[tokio::test]
async fn load_async_converts_a_panicking_store_into_a_storage_error() {
let store: Arc<dyn CredentialStore> = Arc::new(PanickingStore);
let err = load_async(store)
.await
.expect_err("a panicking store must not take down the caller's task");
assert!(
matches!(&err, StorageError::Backend { backend, .. } if backend == "credential-store-task")
);
assert!(
err.to_string().contains("panicked=true"),
"expected the panic flag recorded in the message, got {err}"
);
}
#[tokio::test]
async fn save_async_converts_a_panicking_store_into_a_storage_error() {
let store: Arc<dyn CredentialStore> = Arc::new(PanickingStore);
let err = save_async(store, Session::from_token("tok"))
.await
.expect_err("a panicking store must not take down the caller's task");
assert!(
matches!(&err, StorageError::Backend { backend, .. } if backend == "credential-store-task")
);
assert!(
err.to_string().contains("panicked=true"),
"expected the panic flag recorded in the message, got {err}"
);
}
#[tokio::test]
async fn clear_async_converts_a_panicking_store_into_a_storage_error() {
let store: Arc<dyn CredentialStore> = Arc::new(PanickingStore);
let err = clear_async(store)
.await
.expect_err("a panicking store must not take down the caller's task");
assert!(
matches!(&err, StorageError::Backend { backend, .. } if backend == "credential-store-task")
);
assert!(
err.to_string().contains("panicked=true"),
"expected the panic flag recorded in the message, got {err}"
);
}
#[derive(Debug, Default)]
struct PanickingWithCredentialLikePayloadStore;
impl CredentialStore for PanickingWithCredentialLikePayloadStore {
fn load(&self) -> Result<Session, StorageError> {
panic!("session_token=leaked-secret-should-never-appear-in-storage-error");
}
fn save(&self, _session: &Session) -> Result<(), StorageError> {
panic!("session_token=leaked-secret-should-never-appear-in-storage-error");
}
fn clear(&self) -> Result<(), StorageError> {
panic!("session_token=leaked-secret-should-never-appear-in-storage-error");
}
}
#[tokio::test]
async fn load_async_never_lets_the_panic_payload_reach_the_storage_error() {
let store: Arc<dyn CredentialStore> = Arc::new(PanickingWithCredentialLikePayloadStore);
let err = load_async(store)
.await
.expect_err("a panicking store must not take down the caller's task");
let display = err.to_string();
let debug = format!("{err:?}");
assert!(
!display.contains("leaked-secret") && !debug.contains("leaked-secret"),
"the JoinError's own Display must never be interpolated into a StorageError (S4): \
display={display:?} debug={debug:?}"
);
}
}