loopauth 0.5.0

OAuth 2.0 Authorization Code + PKCE flow for CLI applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use crate::error::TokenStoreError;
use crate::token::{TokenSet, Unvalidated};
use async_trait::async_trait;

/// Persistent storage interface for [`TokenSet`] values.
///
/// Implement this trait to persist tokens across invocations (file, keychain,
/// database, etc.). [`crate::CliTokenClient`] does not manage storage - call
/// [`TokenStore::save`] with the [`crate::TokenSet`] returned by
/// [`crate::CliTokenClient::run_authorization_flow`].
///
/// `load` returns [`TokenSet<Unvalidated>`] so that callers must explicitly call
/// [`TokenSet::into_validated`] after loading, making the promotion from stored
/// bytes to trusted in-memory state a deliberate, visible step.
///
/// # Example
///
/// ```no_run
/// use async_trait::async_trait;
/// use loopauth::{TokenSet, TokenStore, TokenStoreError, Unvalidated};
/// use std::sync::Mutex;
///
/// struct MemoryStore(Mutex<Option<String>>);
///
/// #[async_trait]
/// impl TokenStore for MemoryStore {
///     async fn load(&self) -> Result<Option<TokenSet<Unvalidated>>, TokenStoreError> {
///         let guard = self.0.lock().unwrap();
///         guard
///             .as_deref()
///             .map(|s| {
///                 serde_json::from_str(s)
///                     .map_err(|e| TokenStoreError::Serialization(e.to_string()))
///             })
///             .transpose()
///     }
///
///     async fn save(&self, tokens: &TokenSet) -> Result<(), TokenStoreError> {
///         let json = serde_json::to_string(tokens)
///             .map_err(|e| TokenStoreError::Serialization(e.to_string()))?;
///         *self.0.lock().unwrap() = Some(json);
///         Ok(())
///     }
///
///     async fn clear(&self) -> Result<(), TokenStoreError> {
///         *self.0.lock().unwrap() = None;
///         Ok(())
///     }
/// }
/// ```
#[async_trait]
pub trait TokenStore: Send + Sync {
    /// Load the stored [`TokenSet`], returning `Ok(None)` if none is persisted.
    ///
    /// Returns [`TokenSet<Unvalidated>`] — call [`TokenSet::into_validated`] after
    /// loading to promote the token set to the validated state.
    ///
    /// # Errors
    ///
    /// Returns [`TokenStoreError`] on I/O or deserialization failure.
    async fn load(&self) -> Result<Option<TokenSet<Unvalidated>>, TokenStoreError>;

    /// Persist a [`TokenSet`], overwriting any previously stored value.
    ///
    /// # Errors
    ///
    /// Returns [`TokenStoreError`] on I/O or serialization failure.
    async fn save(&self, tokens: &TokenSet) -> Result<(), TokenStoreError>;

    /// Remove the stored [`TokenSet`].
    ///
    /// # Errors
    ///
    /// Returns [`TokenStoreError`] on I/O failure.
    async fn clear(&self) -> Result<(), TokenStoreError>;
}

#[cfg(test)]
mod tests {
    use super::TokenStore;
    use crate::error::TokenStoreError;
    use crate::token::{TokenSet, Unvalidated};
    use std::time::{Duration, SystemTime};

    struct NoopStore;

    #[async_trait::async_trait]
    impl TokenStore for NoopStore {
        async fn load(&self) -> Result<Option<TokenSet<Unvalidated>>, TokenStoreError> {
            Ok(None)
        }

        async fn save(&self, _tokens: &TokenSet) -> Result<(), TokenStoreError> {
            Ok(())
        }

        async fn clear(&self) -> Result<(), TokenStoreError> {
            Ok(())
        }
    }

    fn make_token_set() -> TokenSet {
        TokenSet::new(
            "access".to_string(),
            None,
            Some(SystemTime::now() + Duration::from_secs(3600)),
            "Bearer".to_string(),
            None,
            Vec::new(),
        )
        .into_validated()
    }

    #[tokio::test]
    async fn noop_store_load_returns_none() {
        let store = NoopStore;
        let result = store.load().await;
        assert!(matches!(result, Ok(None)));
    }

    #[tokio::test]
    async fn noop_store_save_returns_ok() {
        let store = NoopStore;
        let tokens = make_token_set();
        let result = store.save(&tokens).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn noop_store_clear_returns_ok() {
        let store = NoopStore;
        let result = store.clear().await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn token_store_is_object_safe() {
        let store: Box<dyn TokenStore> = Box::new(NoopStore);
        let result = store.load().await;
        assert!(matches!(result, Ok(None)));
    }
}