Skip to main content

auth_framework/storage/
core.rs

1//! Storage backends for authentication data.
2
3use crate::errors::Result;
4use crate::tokens::AuthToken;
5use async_trait::async_trait;
6use serde::{Deserialize, Serialize};
7use std::collections::HashMap;
8use std::sync::{Arc, RwLock};
9use std::time::Duration;
10
11#[cfg(feature = "redis-storage")]
12use crate::errors::StorageError;
13
14/// Trait for authentication data storage backends.
15///
16/// All persistence in `AuthFramework` goes through this trait — tokens,
17/// sessions, and arbitrary key-value data.  Implement it to plug in a
18/// custom database while keeping the rest of the framework unchanged.
19///
20/// # Provided Implementations
21///
22/// | Backend | Type | Feature flag |
23/// |---------|------|-------------|
24/// | In-memory (DashMap) | [`MemoryStorage`] | *(always available)* |
25/// | PostgreSQL | [`PostgresStorage`](crate::storage::postgres::PostgresStorage) | `postgres-storage` |
26/// | Redis | [`RedisStorage`] | `redis-storage` |
27/// | SQLite | [`SqliteStorage`](crate::storage::sqlite::SqliteStorage) | `sqlite-storage` |
28/// | Encrypted wrapper | [`EncryptedStorage`](crate::storage::encryption::EncryptedStorage) | *(always available)* |
29///
30/// # Implementing This Trait
31///
32/// Custom storage backends must:
33///
34/// 1. **Be thread-safe** — the trait requires `Send + Sync`.
35/// 2. **Handle concurrent access** — multiple tasks will read/write
36///    simultaneously. Use connection pooling or interior mutability.
37/// 3. **Honour TTL** — [`store_kv`](Self::store_kv) accepts an optional TTL.
38///    Expired entries must not be returned by [`get_kv`](Self::get_kv).
39/// 4. **Override `list_kv_keys`** — the default returns an error.
40///    Analytics, compliance, and RBAC queries depend on real data.
41/// 5. **Implement `cleanup_expired`** — periodically called to prune stale
42///    tokens and sessions.
43///
44/// # Example (skeleton)
45///
46/// ```rust,no_run
47/// use auth_framework::storage::{AuthStorage, SessionData};
48/// use auth_framework::tokens::AuthToken;
49/// use auth_framework::errors::Result;
50/// use async_trait::async_trait;
51/// use std::time::Duration;
52///
53/// struct MyStorage { /* ... */ }
54///
55/// #[async_trait]
56/// impl AuthStorage for MyStorage {
57///     async fn store_token(&self, token: &AuthToken) -> Result<()> { todo!() }
58///     async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> { todo!() }
59///     async fn get_token_by_access_token(&self, _: &str) -> Result<Option<AuthToken>> { todo!() }
60///     async fn update_token(&self, token: &AuthToken) -> Result<()> { todo!() }
61///     async fn delete_token(&self, token_id: &str) -> Result<()> { todo!() }
62///     async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> { todo!() }
63///     async fn store_session(&self, id: &str, data: &SessionData) -> Result<()> { todo!() }
64///     async fn get_session(&self, id: &str) -> Result<Option<SessionData>> { todo!() }
65///     async fn delete_session(&self, id: &str) -> Result<()> { todo!() }
66///     async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> { todo!() }
67///     async fn count_active_sessions(&self) -> Result<u64> { todo!() }
68///     async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> { todo!() }
69///     async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> { todo!() }
70///     async fn delete_kv(&self, key: &str) -> Result<()> { todo!() }
71///     async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> { todo!() }
72///     async fn cleanup_expired(&self) -> Result<()> { todo!() }
73/// }
74/// ```
75#[async_trait]
76pub trait AuthStorage: Send + Sync {
77    /// Bulk store tokens.
78    async fn store_tokens_bulk(&self, tokens: &[AuthToken]) -> Result<()> {
79        for token in tokens {
80            self.store_token(token).await?;
81        }
82        Ok(())
83    }
84
85    /// Bulk delete tokens by ID.
86    async fn delete_tokens_bulk(&self, token_ids: &[String]) -> Result<()> {
87        for token_id in token_ids {
88            self.delete_token(token_id).await?;
89        }
90        Ok(())
91    }
92
93    /// Bulk store sessions.
94    async fn store_sessions_bulk(&self, sessions: &[(String, SessionData)]) -> Result<()> {
95        for (session_id, data) in sessions {
96            self.store_session(session_id, data).await?;
97        }
98        Ok(())
99    }
100
101    /// Bulk delete sessions by ID.
102    async fn delete_sessions_bulk(&self, session_ids: &[String]) -> Result<()> {
103        for session_id in session_ids {
104            self.delete_session(session_id).await?;
105        }
106        Ok(())
107    }
108    /// Store a token.
109    async fn store_token(&self, token: &AuthToken) -> Result<()>;
110
111    /// Retrieve a token by ID.
112    async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>>;
113
114    /// Retrieve a token by access token string.
115    async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>>;
116
117    /// Update a token.
118    async fn update_token(&self, token: &AuthToken) -> Result<()>;
119
120    /// Delete a token.
121    async fn delete_token(&self, token_id: &str) -> Result<()>;
122
123    /// List all tokens for a user.
124    async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>>;
125
126    /// Store session data.
127    async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()>;
128
129    /// Retrieve session data.
130    async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>>;
131
132    /// Delete session data.
133    async fn delete_session(&self, session_id: &str) -> Result<()>;
134
135    /// List all sessions for a user.
136    async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>>;
137
138    /// Count currently active sessions (non-expired)
139    async fn count_active_sessions(&self) -> Result<u64>;
140
141    /// Store arbitrary key-value data with expiration.
142    async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()>;
143
144    /// Store `value` under `key` only if no live entry exists. Returns whether it was stored.
145    ///
146    /// This is a compare-and-set: of several simultaneous callers exactly one gets `true`.
147    /// Single-use markers (refresh-token redemption, TOTP steps, WebAuthn sessions, PKCE codes)
148    /// depend on that, so a backend **must** implement it atomically; there is no default that
149    /// could be correct for every store (a `get_kv` followed by `store_kv` is not atomic).
150    /// The default therefore fails with an error, and the paths that need a claim fail with it
151    /// rather than run without the guarantee. The memory, SQLite (both crates), PostgreSQL,
152    /// Redis, unified and encrypted-wrapper backends and the test-only `MockStorage` implement it.
153    async fn store_kv_if_absent(
154        &self,
155        _key: &str,
156        _value: &[u8],
157        _ttl: Option<Duration>,
158    ) -> Result<bool> {
159        Err(crate::errors::AuthError::Storage(
160            crate::errors::StorageError::operation_failed(
161                "this storage backend does not implement store_kv_if_absent, which the \
162                 single-use claims (refresh-token redemption, TOTP steps, WebAuthn sessions, \
163                 PKCE codes) require to be atomic; implement it as a compare-and-set"
164                    .to_string(),
165            ),
166        ))
167    }
168
169    /// Retrieve arbitrary key-value data.
170    async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>>;
171
172    /// Remaining time-to-live of a key-value entry.
173    ///
174    /// Returns `Ok(None)` when the key is absent, has no expiry, **or the
175    /// backend does not track TTLs** (the default). Callers that must carry
176    /// an entry's lifetime across a copy (backup/restore, migration) use
177    /// this together with [`get_kv`](Self::get_kv); a backend that honours
178    /// the TTL passed to [`store_kv`](Self::store_kv) should override it so
179    /// those entries do not silently become non-expiring. An entry that
180    /// `get_kv` would still return but that expires within the backend's
181    /// time resolution reports `Some(Duration::ZERO)`, never `None`.
182    async fn get_kv_ttl(&self, _key: &str) -> Result<Option<Duration>> {
183        Ok(None)
184    }
185
186    /// Whether [`get_kv_ttl`](Self::get_kv_ttl) reports the TTLs given to
187    /// [`store_kv`](Self::store_kv). `false` (the default) means a TTL is
188    /// invisible to callers, so anything that copies entries (migration,
189    /// backup/restore) cannot preserve expiry. A backend that overrides
190    /// [`get_kv_ttl`](Self::get_kv_ttl) must override this too (return
191    /// `true`), otherwise it is treated as TTL-blind.
192    fn tracks_kv_ttl(&self) -> bool {
193        false
194    }
195
196    /// Whether this storage encrypts KV values at rest itself (i.e. it is,
197    /// or wraps, an [`EncryptedStorage`](crate::storage::encryption::EncryptedStorage)).
198    /// `false` (the default) means values reach the backend as given. A
199    /// wrapper around an `EncryptedStorage` must forward this, or startup
200    /// will wrongly report its values as unencrypted.
201    fn encrypts_kv_at_rest(&self) -> bool {
202        false
203    }
204
205    /// Delete arbitrary key-value data.
206    async fn delete_kv(&self, key: &str) -> Result<()>;
207
208    /// List keys with a specific prefix.
209    ///
210    /// **Important:** every storage backend must override this method. The default
211    /// returns an error: an empty list would be indistinguishable from "no keys", and
212    /// analytics, compliance and RBAC queries would silently operate on no data.
213    /// Expired keys are not listed.
214    async fn list_kv_keys(&self, _prefix: &str) -> Result<Vec<String>> {
215        Err(crate::errors::AuthError::Storage(
216            crate::errors::StorageError::operation_failed(
217                "this storage backend does not implement list_kv_keys, which analytics, \
218                 compliance, RBAC and maintenance listing require; implement it to return \
219                 the unexpired KV keys that start with the prefix"
220                    .to_string(),
221            ),
222        ))
223    }
224
225    /// Clean up expired data.
226    async fn cleanup_expired(&self) -> Result<()>;
227}
228
229/// Lets a boxed `Arc<dyn AuthStorage>` coming out of the storage factory be
230/// wrapped in [`crate::storage::encryption::EncryptedStorage`] without
231/// downcasting to a concrete backend type first.
232///
233/// Deliberately scoped to the trait-object case only (`Arc<dyn
234/// AuthStorage>`), not a generic `impl<T: AuthStorage + ?Sized> AuthStorage
235/// for Arc<T>`: a generic impl would apply to every `Arc<ConcreteBackend>`
236/// too, and Rust's method resolution prefers an exact-type impl over
237/// autoderef -- so `some_arc.get_session(..)` would resolve to this impl's
238/// `(**self).get_session(..)` indirection instead of calling
239/// `ConcreteBackend::get_session` directly, adding an extra `async_trait`
240/// boxed-future hop to every storage call made through an `Arc<Concrete>`
241/// anywhere in the crate (including benchmarks and tests), not just the
242/// one factory path that actually needs this. Measured: this cost a real
243/// ~20-30% regression on the `session_operations/get_session` benchmark
244/// before being scoped down to `dyn AuthStorage` here.
245#[async_trait]
246impl AuthStorage for Arc<dyn AuthStorage> {
247    async fn store_tokens_bulk(&self, tokens: &[AuthToken]) -> Result<()> {
248        (**self).store_tokens_bulk(tokens).await
249    }
250
251    async fn delete_tokens_bulk(&self, token_ids: &[String]) -> Result<()> {
252        (**self).delete_tokens_bulk(token_ids).await
253    }
254
255    async fn store_sessions_bulk(&self, sessions: &[(String, SessionData)]) -> Result<()> {
256        (**self).store_sessions_bulk(sessions).await
257    }
258
259    async fn delete_sessions_bulk(&self, session_ids: &[String]) -> Result<()> {
260        (**self).delete_sessions_bulk(session_ids).await
261    }
262
263    async fn store_token(&self, token: &AuthToken) -> Result<()> {
264        (**self).store_token(token).await
265    }
266
267    async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
268        (**self).get_token(token_id).await
269    }
270
271    async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>> {
272        (**self).get_token_by_access_token(access_token).await
273    }
274
275    async fn update_token(&self, token: &AuthToken) -> Result<()> {
276        (**self).update_token(token).await
277    }
278
279    async fn delete_token(&self, token_id: &str) -> Result<()> {
280        (**self).delete_token(token_id).await
281    }
282
283    async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
284        (**self).list_user_tokens(user_id).await
285    }
286
287    async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()> {
288        (**self).store_session(session_id, data).await
289    }
290
291    async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
292        (**self).get_session(session_id).await
293    }
294
295    async fn delete_session(&self, session_id: &str) -> Result<()> {
296        (**self).delete_session(session_id).await
297    }
298
299    async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> {
300        (**self).list_user_sessions(user_id).await
301    }
302
303    async fn count_active_sessions(&self) -> Result<u64> {
304        (**self).count_active_sessions().await
305    }
306
307    async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> {
308        (**self).store_kv(key, value, ttl).await
309    }
310
311    async fn store_kv_if_absent(
312        &self,
313        key: &str,
314        value: &[u8],
315        ttl: Option<Duration>,
316    ) -> Result<bool> {
317        (**self).store_kv_if_absent(key, value, ttl).await
318    }
319
320    async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> {
321        (**self).get_kv(key).await
322    }
323
324    async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
325        (**self).get_kv_ttl(key).await
326    }
327
328    fn tracks_kv_ttl(&self) -> bool {
329        (**self).tracks_kv_ttl()
330    }
331
332    async fn delete_kv(&self, key: &str) -> Result<()> {
333        (**self).delete_kv(key).await
334    }
335
336    fn encrypts_kv_at_rest(&self) -> bool {
337        (**self).encrypts_kv_at_rest()
338    }
339
340    async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> {
341        (**self).list_kv_keys(prefix).await
342    }
343
344    async fn cleanup_expired(&self) -> Result<()> {
345        (**self).cleanup_expired().await
346    }
347}
348
349/// Session data stored in the backend.
350///
351/// All fields are public for serialization flexibility. When constructing
352/// a new session prefer [`SessionData::new`] which initialises timestamps
353/// consistently.
354///
355/// # Chainable construction
356///
357/// ```rust,ignore
358/// let session = SessionData::new("sess-1", "user-1", Duration::from_secs(3600))
359///     .ip_address("127.0.0.1")
360///     .user_agent("Mozilla/5.0")
361///     .with_data("role", json!("admin"));
362/// ```
363///
364/// The older [`SessionData::with_metadata`] helper sets both IP and
365/// user-agent in a single call and remains available.
366///
367/// # Invariants (not enforced at the type level)
368///
369/// * `created_at <= last_activity`
370/// * `created_at < expires_at`
371/// * `last_activity` is updated on every authenticated access.
372/// * `data` may contain arbitrary application-specific key/value pairs
373///   — the framework never reads them.
374#[derive(Debug, Clone, Serialize, Deserialize)]
375pub struct SessionData {
376    /// Session ID
377    pub session_id: String,
378
379    /// User ID associated with this session
380    pub user_id: String,
381
382    /// When the session was created
383    pub created_at: chrono::DateTime<chrono::Utc>,
384
385    /// When the session expires
386    pub expires_at: chrono::DateTime<chrono::Utc>,
387
388    /// Last activity timestamp
389    pub last_activity: chrono::DateTime<chrono::Utc>,
390
391    /// IP address of the session
392    pub ip_address: Option<String>,
393
394    /// User agent
395    pub user_agent: Option<String>,
396
397    /// Custom session data
398    pub data: HashMap<String, serde_json::Value>,
399}
400
401/// In-memory storage implementation (for development/testing only).
402///
403/// # ⚠️ Production Unsuitability
404///
405/// This implementation is NOT recommended for production use:
406/// - **Data Loss**: All stored tokens and sessions are lost on process restart
407/// - **Memory Growth**: No automatic cleanup; memory usage grows unbounded
408/// - **TTL Ignored**: Expiration times are not enforced; expired tokens may be returned
409/// - **Single Instance**: Cannot be used in multi-instance deployments
410/// - **No Persistence**: No option to back up or export data
411///
412/// Use `PostgresStorage`, `RedisStorage`, or `SqliteStorage` for production.
413///
414/// SECURITY UPDATE: Now uses DashMap for deadlock-free concurrent operations
415#[derive(Debug, Clone)]
416pub struct MemoryStorage {
417    // Primary storage using DashMap for deadlock-free operations
418    inner: crate::storage::dashmap_memory::DashMapMemoryStorage,
419    // RBAC storage still uses RwLock for compatibility (lower concurrency requirements)
420    roles: Arc<RwLock<HashMap<String, crate::authorization::AbacRole>>>,
421    user_roles: Arc<RwLock<Vec<crate::authorization::UserRole>>>,
422}
423
424/// Redis storage implementation.
425#[cfg(feature = "redis-storage")]
426#[derive(Debug, Clone)]
427pub struct RedisStorage {
428    client: redis::Client,
429    key_prefix: String,
430}
431
432impl Default for MemoryStorage {
433    fn default() -> Self {
434        Self::new()
435    }
436}
437
438impl MemoryStorage {
439    /// Create a new in-memory storage.
440    pub fn new() -> Self {
441        Self {
442            inner: crate::storage::dashmap_memory::DashMapMemoryStorage::new(),
443            roles: Arc::new(RwLock::new(HashMap::new())),
444            user_roles: Arc::new(RwLock::new(Vec::new())),
445        }
446    }
447}
448// In-memory AuthorizationStorage implementation for RBAC examples
449#[async_trait::async_trait]
450impl crate::authorization::AuthorizationStorage for MemoryStorage {
451    async fn store_role(&self, role: &crate::authorization::AbacRole) -> crate::errors::Result<()> {
452        let mut roles = self.roles.write().map_err(|_| {
453            crate::errors::AuthError::internal(
454                "Lock poisoned — a prior thread panicked while holding this lock",
455            )
456        })?;
457        roles.insert(role.id.clone(), role.clone());
458        Ok(())
459    }
460
461    async fn get_role(
462        &self,
463        role_id: &str,
464    ) -> crate::errors::Result<Option<crate::authorization::AbacRole>> {
465        let roles = self.roles.read().map_err(|_| {
466            crate::errors::AuthError::internal(
467                "Lock poisoned — a prior thread panicked while holding this lock",
468            )
469        })?;
470        Ok(roles.get(role_id).cloned())
471    }
472
473    async fn update_role(
474        &self,
475        role: &crate::authorization::AbacRole,
476    ) -> crate::errors::Result<()> {
477        let mut roles = self.roles.write().map_err(|_| {
478            crate::errors::AuthError::internal(
479                "Lock poisoned — a prior thread panicked while holding this lock",
480            )
481        })?;
482        roles.insert(role.id.clone(), role.clone());
483        Ok(())
484    }
485
486    async fn delete_role(&self, role_id: &str) -> crate::errors::Result<()> {
487        let mut roles = self.roles.write().map_err(|_| {
488            crate::errors::AuthError::internal(
489                "Lock poisoned — a prior thread panicked while holding this lock",
490            )
491        })?;
492        roles.remove(role_id);
493        Ok(())
494    }
495
496    async fn list_roles(&self) -> crate::errors::Result<Vec<crate::authorization::AbacRole>> {
497        let roles = self.roles.read().map_err(|_| {
498            crate::errors::AuthError::internal(
499                "Lock poisoned — a prior thread panicked while holding this lock",
500            )
501        })?;
502        Ok(roles.values().cloned().collect())
503    }
504
505    async fn assign_role(
506        &self,
507        user_role: &crate::authorization::UserRole,
508    ) -> crate::errors::Result<()> {
509        let mut user_roles = self.user_roles.write().map_err(|_| {
510            crate::errors::AuthError::internal(
511                "Lock poisoned — a prior thread panicked while holding this lock",
512            )
513        })?;
514        user_roles.push(user_role.clone());
515        Ok(())
516    }
517
518    async fn remove_role(&self, user_id: &str, role_id: &str) -> crate::errors::Result<()> {
519        let mut user_roles = self.user_roles.write().map_err(|_| {
520            crate::errors::AuthError::internal(
521                "Lock poisoned — a prior thread panicked while holding this lock",
522            )
523        })?;
524        user_roles.retain(|ur| ur.user_id != user_id || ur.role_id != role_id);
525        Ok(())
526    }
527
528    async fn get_user_roles(
529        &self,
530        user_id: &str,
531    ) -> crate::errors::Result<Vec<crate::authorization::UserRole>> {
532        let user_roles = self.user_roles.read().map_err(|_| {
533            crate::errors::AuthError::internal(
534                "Lock poisoned — a prior thread panicked while holding this lock",
535            )
536        })?;
537        Ok(user_roles
538            .iter()
539            .filter(|ur| ur.user_id == user_id)
540            .cloned()
541            .collect())
542    }
543
544    async fn get_role_users(
545        &self,
546        role_id: &str,
547    ) -> crate::errors::Result<Vec<crate::authorization::UserRole>> {
548        let user_roles = self.user_roles.read().map_err(|_| {
549            crate::errors::AuthError::internal(
550                "Lock poisoned — a prior thread panicked while holding this lock",
551            )
552        })?;
553        Ok(user_roles
554            .iter()
555            .filter(|ur| ur.role_id == role_id)
556            .cloned()
557            .collect())
558    }
559}
560
561#[async_trait]
562impl AuthStorage for MemoryStorage {
563    async fn store_token(&self, token: &AuthToken) -> Result<()> {
564        // Delegate to DashMap implementation for deadlock-free operations
565        self.inner.store_token(token).await
566    }
567
568    async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
569        // Delegate to DashMap implementation for deadlock-free operations
570        self.inner.get_token(token_id).await
571    }
572
573    async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>> {
574        // Delegate to DashMap implementation for deadlock-free operations
575        self.inner.get_token_by_access_token(access_token).await
576    }
577
578    async fn update_token(&self, token: &AuthToken) -> Result<()> {
579        // Delegate to DashMap implementation for deadlock-free operations
580        self.inner.update_token(token).await
581    }
582
583    async fn delete_token(&self, token_id: &str) -> Result<()> {
584        // Delegate to DashMap implementation for deadlock-free operations
585        self.inner.delete_token(token_id).await
586    }
587
588    async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
589        // Delegate to DashMap implementation for deadlock-free operations
590        self.inner.list_user_tokens(user_id).await
591    }
592
593    async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()> {
594        // Delegate to DashMap implementation for deadlock-free operations
595        self.inner.store_session(session_id, data).await
596    }
597
598    async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
599        // Delegate to DashMap implementation for deadlock-free operations
600        self.inner.get_session(session_id).await
601    }
602
603    async fn delete_session(&self, session_id: &str) -> Result<()> {
604        // Delegate to DashMap implementation for deadlock-free operations
605        self.inner.delete_session(session_id).await
606    }
607
608    async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> {
609        // Delegate to DashMap implementation for deadlock-free operations
610        self.inner.list_user_sessions(user_id).await
611    }
612
613    async fn count_active_sessions(&self) -> Result<u64> {
614        // Delegate to DashMap implementation for deadlock-free operations
615        self.inner.count_active_sessions().await
616    }
617
618    async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> {
619        // Delegate to DashMap implementation for deadlock-free operations
620        self.inner.store_kv(key, value, ttl).await
621    }
622
623    async fn store_kv_if_absent(
624        &self,
625        key: &str,
626        value: &[u8],
627        ttl: Option<Duration>,
628    ) -> Result<bool> {
629        self.inner.store_kv_if_absent(key, value, ttl).await
630    }
631
632    async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> {
633        // Delegate to DashMap implementation for deadlock-free operations
634        self.inner.get_kv(key).await
635    }
636
637    async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
638        self.inner.get_kv_ttl(key).await
639    }
640
641    fn tracks_kv_ttl(&self) -> bool {
642        self.inner.tracks_kv_ttl()
643    }
644
645    async fn delete_kv(&self, key: &str) -> Result<()> {
646        // Delegate to DashMap implementation for deadlock-free operations
647        self.inner.delete_kv(key).await
648    }
649
650    async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> {
651        Ok(self.inner.list_kv_keys_by_prefix(prefix))
652    }
653
654    async fn cleanup_expired(&self) -> Result<()> {
655        // Delegate to DashMap implementation for deadlock-free operations
656        self.inner.cleanup_expired().await
657    }
658}
659
660#[cfg(feature = "redis-storage")]
661impl RedisStorage {
662    /// Create a new Redis storage.
663    pub fn new(redis_url: &str, key_prefix: impl Into<String>) -> Result<Self> {
664        let client = redis::Client::open(redis_url).map_err(|e| {
665            StorageError::connection_failed(format!("Redis connection failed: {e}"))
666        })?;
667
668        Ok(Self {
669            client,
670            key_prefix: key_prefix.into(),
671        })
672    }
673
674    /// Get a Redis connection.
675    async fn get_connection(&self) -> Result<redis::aio::MultiplexedConnection> {
676        self.client
677            .get_multiplexed_async_connection()
678            .await
679            .map_err(|e| {
680                StorageError::connection_failed(format!("Failed to get Redis connection: {e}"))
681                    .into()
682            })
683    }
684
685    /// Generate a key with the configured prefix.
686    fn key(&self, suffix: &str) -> String {
687        format!("{}{}", self.key_prefix, suffix)
688    }
689
690    /// Key of the access-token -> token-id mapping. The raw access token is a
691    /// bearer credential and is never used as a key name (see
692    /// [`crate::storage::key_names`]).
693    fn access_mapping_key(&self, access_token: &str) -> String {
694        self.key(&format!(
695            "access_token_h:{}",
696            crate::storage::key_names::digest("access_token", access_token)
697        ))
698    }
699
700    /// The pre-fix name, kept only to read-and-migrate or delete old rows.
701    fn legacy_access_mapping_key(&self, access_token: &str) -> String {
702        self.key(&format!("access_token:{access_token}"))
703    }
704
705    /// Key of a session record; the session id is a bearer credential.
706    fn session_key(&self, session_id: &str) -> String {
707        self.key(&format!(
708            "session_h:{}",
709            crate::storage::key_names::digest("session", session_id)
710        ))
711    }
712
713    /// The pre-fix name, kept only to read-and-migrate or delete old rows.
714    fn legacy_session_key(&self, session_id: &str) -> String {
715        self.key(&format!("session:{session_id}"))
716    }
717
718    /// Every session key, under the digest name and under the legacy name.
719    /// Two exact-prefix patterns, so nothing else sharing the key prefix
720    /// matches. A session present under both names (a crash between the two
721    /// writes of a store) is returned under both names; `count_active_sessions`
722    /// counts it once.
723    async fn session_keys(
724        &self,
725        conn: &mut redis::aio::MultiplexedConnection,
726    ) -> Result<Vec<String>> {
727        let mut keys = Vec::new();
728        for pattern in [self.key("session_h:*"), self.key("session:*")] {
729            let found: Vec<String> = redis::cmd("KEYS")
730                .arg(&pattern)
731                .query_async(&mut *conn)
732                .await
733                .map_err(|e| {
734                    StorageError::operation_failed(format!("Failed to scan sessions: {e}"))
735                })?;
736            keys.extend(found);
737        }
738        Ok(keys)
739    }
740
741    /// Read `new_key`; on a miss, move a row stored under `legacy_key` (the raw
742    /// credential name used before digest naming) to `new_key`, keeping its
743    /// remaining lifetime, and return it.
744    async fn get_migrating(&self, new_key: &str, legacy_key: &str) -> Result<Option<String>> {
745        let mut conn = self.get_connection().await?;
746        // Plain read first: it needs no scripting permission, and a digest-named
747        // row is the common case.
748        let value: Option<String> = redis::cmd("GET")
749            .arg(new_key)
750            .query_async(&mut conn)
751            .await
752            .map_err(|e| StorageError::operation_failed(format!("Failed to read key: {e}")))?;
753        if value.is_some() {
754            // A legacy twin can only be left by an interrupted write and still
755            // holds the raw id in its name: drop it (best effort).
756            let _ = redis::cmd("DEL")
757                .arg(legacy_key)
758                .query_async::<usize>(&mut conn)
759                .await;
760            return Ok(value);
761        }
762        // One Lua script, so a concurrent store or delete cannot interleave with the
763        // move: it never overwrites a row already at `new_key` and never recreates
764        // a row that was deleted.
765        const MIGRATE: &str = r#"
766            local l = redis.call('GET', KEYS[2])
767            if not l then return redis.call('GET', KEYS[1]) end
768            local v = redis.call('GET', KEYS[1])
769            if v then
770                redis.call('DEL', KEYS[2])
771                return v
772            end
773            local t = redis.call('PTTL', KEYS[2])
774            if t > 0 then
775                redis.call('SET', KEYS[1], l, 'PX', t)
776            elseif t == -1 then
777                redis.call('SET', KEYS[1], l)
778            else
779                return false
780            end
781            redis.call('DEL', KEYS[2])
782            return l
783        "#;
784        match redis::Script::new(MIGRATE)
785            .key(new_key)
786            .key(legacy_key)
787            .invoke_async::<Option<String>>(&mut conn)
788            .await
789        {
790            Ok(value) => Ok(value),
791            Err(script_err) => {
792                // Scripting denied (restricted ACL) or unavailable: serve the row
793                // where it is. It moves once scripts are allowed or the record is
794                // rewritten.
795                tracing::warn!(
796                    error = %script_err,
797                    "legacy-name migration script failed; serving the row unmigrated"
798                );
799                let legacy: Option<String> = redis::cmd("GET")
800                    .arg(legacy_key)
801                    .query_async(&mut conn)
802                    .await
803                    .map_err(|e| {
804                        StorageError::operation_failed(format!("Failed to read key: {e}"))
805                    })?;
806                Ok(legacy)
807            }
808        }
809    }
810
811    /// Delete a key left under a pre-fix (raw credential) name, if any.
812    async fn del_legacy(&self, legacy_key: &str) -> Result<()> {
813        let mut conn = self.get_connection().await?;
814        let _: () = redis::cmd("DEL")
815            .arg(legacy_key)
816            .query_async(&mut conn)
817            .await
818            .map_err(|e| {
819                StorageError::operation_failed(format!("Failed to remove legacy key: {e}"))
820            })?;
821        Ok(())
822    }
823}
824
825#[cfg(feature = "redis-storage")]
826#[async_trait]
827impl AuthStorage for RedisStorage {
828    async fn store_token(&self, token: &AuthToken) -> Result<()> {
829        let mut conn = self.get_connection().await?;
830        let token_json = serde_json::to_string(token)
831            .map_err(|e| StorageError::serialization(format!("Token serialization failed: {e}")))?;
832
833        let token_key = self.key(&format!("token:{}", token.token_id));
834        let access_token_key = self.access_mapping_key(&token.access_token);
835        let user_tokens_key = self.key(&format!("user_tokens:{}", token.user_id));
836
837        // Calculate TTL
838        let ttl = token.time_until_expiry().as_secs().max(1);
839
840        // Store token data
841        let _: () = redis::cmd("SETEX")
842            .arg(&token_key)
843            .arg(ttl)
844            .arg(&token_json)
845            .query_async(&mut conn)
846            .await
847            .map_err(|e| StorageError::operation_failed(format!("Failed to store token: {e}")))?;
848
849        // Store access token mapping
850        let _: () = redis::cmd("SETEX")
851            .arg(&access_token_key)
852            .arg(ttl)
853            .arg(&token.token_id)
854            .query_async(&mut conn)
855            .await
856            .map_err(|e| {
857                StorageError::operation_failed(format!("Failed to store access token mapping: {e}"))
858            })?;
859
860        // Drop a mapping left under the pre-fix name (it held the raw token).
861        self.del_legacy(&self.legacy_access_mapping_key(&token.access_token))
862            .await?;
863
864        // Add to user tokens set
865        let _: () = redis::cmd("SADD")
866            .arg(&user_tokens_key)
867            .arg(&token.token_id)
868            .query_async(&mut conn)
869            .await
870            .map_err(|e| {
871                StorageError::operation_failed(format!("Failed to add token to user set: {e}"))
872            })?;
873
874        Ok(())
875    }
876
877    async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
878        let mut conn = self.get_connection().await?;
879        let token_key = self.key(&format!("token:{token_id}"));
880
881        let token_json: Option<String> = redis::cmd("GET")
882            .arg(&token_key)
883            .query_async(&mut conn)
884            .await
885            .map_err(|e| StorageError::operation_failed(format!("Failed to get token: {e}")))?;
886
887        if let Some(json) = token_json {
888            let token: AuthToken = serde_json::from_str(&json).map_err(|e| {
889                StorageError::serialization(format!("Token deserialization failed: {e}"))
890            })?;
891            Ok(Some(token))
892        } else {
893            Ok(None)
894        }
895    }
896
897    async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>> {
898        let token_id = self
899            .get_migrating(
900                &self.access_mapping_key(access_token),
901                &self.legacy_access_mapping_key(access_token),
902            )
903            .await?;
904
905        if let Some(token_id) = token_id {
906            self.get_token(&token_id).await
907        } else {
908            Ok(None)
909        }
910    }
911
912    async fn update_token(&self, token: &AuthToken) -> Result<()> {
913        // Same as store_token for Redis
914        self.store_token(token).await
915    }
916
917    async fn delete_token(&self, token_id: &str) -> Result<()> {
918        let mut conn = self.get_connection().await?;
919
920        // Get token first to get access token and user ID
921        if let Some(token) = self.get_token(token_id).await? {
922            let token_key = self.key(&format!("token:{token_id}"));
923            let access_token_key = self.access_mapping_key(&token.access_token);
924            let user_tokens_key = self.key(&format!("user_tokens:{}", token.user_id));
925            self.del_legacy(&self.legacy_access_mapping_key(&token.access_token))
926                .await?;
927
928            // Delete token data
929            let _: () = redis::cmd("DEL")
930                .arg(&token_key)
931                .query_async(&mut conn)
932                .await
933                .map_err(|e| {
934                    StorageError::operation_failed(format!("Failed to delete token: {e}"))
935                })?;
936
937            // Delete access token mapping
938            let _: () = redis::cmd("DEL")
939                .arg(&access_token_key)
940                .query_async(&mut conn)
941                .await
942                .map_err(|e| {
943                    StorageError::operation_failed(format!(
944                        "Failed to delete access token mapping: {e}"
945                    ))
946                })?;
947
948            // Remove from user tokens set
949            let _: () = redis::cmd("SREM")
950                .arg(&user_tokens_key)
951                .arg(token_id)
952                .query_async(&mut conn)
953                .await
954                .map_err(|e| {
955                    StorageError::operation_failed(format!(
956                        "Failed to remove token from user set: {e}"
957                    ))
958                })?;
959        }
960
961        Ok(())
962    }
963
964    async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
965        let mut conn = self.get_connection().await?;
966        let user_tokens_key = self.key(&format!("user_tokens:{user_id}"));
967
968        let token_ids: Vec<String> = redis::cmd("SMEMBERS")
969            .arg(&user_tokens_key)
970            .query_async(&mut conn)
971            .await
972            .map_err(|e| {
973                StorageError::operation_failed(format!("Failed to get user tokens: {e}"))
974            })?;
975
976        let mut tokens = Vec::new();
977        for token_id in token_ids {
978            if let Some(token) = self.get_token(&token_id).await? {
979                tokens.push(token);
980            }
981        }
982
983        Ok(tokens)
984    }
985
986    async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()> {
987        let mut conn = self.get_connection().await?;
988        let session_key = self.session_key(session_id);
989
990        let session_json = serde_json::to_string(data).map_err(|e| {
991            StorageError::serialization(format!("Session serialization failed: {e}"))
992        })?;
993
994        let ttl = (data.expires_at - chrono::Utc::now()).num_seconds().max(1);
995
996        let _: () = redis::cmd("SETEX")
997            .arg(&session_key)
998            .arg(ttl)
999            .arg(&session_json)
1000            .query_async(&mut conn)
1001            .await
1002            .map_err(|e| StorageError::operation_failed(format!("Failed to store session: {e}")))?;
1003
1004        // Drop a record left under the pre-fix name (it held the raw session id).
1005        self.del_legacy(&self.legacy_session_key(session_id))
1006            .await?;
1007
1008        Ok(())
1009    }
1010
1011    async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
1012        let session_json = self
1013            .get_migrating(
1014                &self.session_key(session_id),
1015                &self.legacy_session_key(session_id),
1016            )
1017            .await?;
1018
1019        if let Some(json) = session_json {
1020            let session: SessionData = serde_json::from_str(&json).map_err(|e| {
1021                StorageError::serialization(format!("Session deserialization failed: {e}"))
1022            })?;
1023            Ok(Some(session))
1024        } else {
1025            Ok(None)
1026        }
1027    }
1028
1029    async fn delete_session(&self, session_id: &str) -> Result<()> {
1030        let mut conn = self.get_connection().await?;
1031        let session_key = self.session_key(session_id);
1032
1033        // Legacy name first: a migration that runs in between then finds no
1034        // legacy row to move, so a deleted session cannot be recreated.
1035        self.del_legacy(&self.legacy_session_key(session_id))
1036            .await?;
1037        let _: () = redis::cmd("DEL")
1038            .arg(&session_key)
1039            .query_async(&mut conn)
1040            .await
1041            .map_err(|e| {
1042                StorageError::operation_failed(format!("Failed to delete session: {e}"))
1043            })?;
1044
1045        Ok(())
1046    }
1047
1048    async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> {
1049        let mut conn = self.get_connection().await?;
1050        let keys = self.session_keys(&mut conn).await?;
1051
1052        let mut user_sessions = Vec::new();
1053        let mut seen = std::collections::HashSet::new();
1054
1055        // Check each session to see if it belongs to the user
1056        let legacy_prefix = self.legacy_session_key("");
1057        for key in keys {
1058            // A row still under the pre-fix name is moved to its digest name as
1059            // it is listed, so it stops exposing the raw session id in key names.
1060            let session_json = match key.strip_prefix(&legacy_prefix) {
1061                Some(session_id) => self
1062                    .get_migrating(&self.session_key(session_id), &key)
1063                    .await
1064                    .ok()
1065                    .flatten(),
1066                None => redis::cmd("GET")
1067                    .arg(&key)
1068                    .query_async::<Option<String>>(&mut conn)
1069                    .await
1070                    .ok()
1071                    .flatten(),
1072            };
1073            if let Some(session_json) = session_json
1074                && let Ok(session) = serde_json::from_str::<SessionData>(&session_json)
1075                && session.user_id == user_id
1076                && !session.is_expired()
1077                && seen.insert(session.session_id.clone())
1078            {
1079                user_sessions.push(session);
1080            }
1081        }
1082
1083        Ok(user_sessions)
1084    }
1085
1086    async fn store_kv_if_absent(
1087        &self,
1088        key: &str,
1089        value: &[u8],
1090        ttl: Option<Duration>,
1091    ) -> Result<bool> {
1092        let mut conn = self.get_connection().await?;
1093        let storage_key = self.key(&format!("kv:{key}"));
1094        // SET ... NX [PX ms]: atomic; the reply is OK when set and nil when the key exists.
1095        let mut cmd = redis::cmd("SET");
1096        cmd.arg(&storage_key).arg(value).arg("NX");
1097        if let Some(ttl) = ttl {
1098            let millis = u64::try_from(ttl.as_millis()).unwrap_or(u64::MAX).max(1);
1099            cmd.arg("PX").arg(millis);
1100        }
1101        let reply: Option<String> = cmd.query_async(&mut conn).await.map_err(|e| {
1102            StorageError::operation_failed(format!("Failed to store KV if absent: {e}"))
1103        })?;
1104        Ok(reply.is_some())
1105    }
1106
1107    async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> {
1108        let mut conn = self.get_connection().await?;
1109        let storage_key = self.key(&format!("kv:{key}"));
1110
1111        if let Some(ttl) = ttl {
1112            // PSETEX, not SETEX: a remaining TTL under one second must not
1113            // become `SETEX key 0 ...`, which Redis rejects.
1114            let millis = u64::try_from(ttl.as_millis()).unwrap_or(u64::MAX).max(1);
1115            let _: () = redis::cmd("PSETEX")
1116                .arg(&storage_key)
1117                .arg(millis)
1118                .arg(value)
1119                .query_async(&mut conn)
1120                .await
1121                .map_err(|e| {
1122                    StorageError::operation_failed(format!("Failed to store KV with TTL: {e}"))
1123                })?;
1124        } else {
1125            let _: () = redis::cmd("SET")
1126                .arg(&storage_key)
1127                .arg(value)
1128                .query_async(&mut conn)
1129                .await
1130                .map_err(|e| StorageError::operation_failed(format!("Failed to store KV: {e}")))?;
1131        }
1132
1133        Ok(())
1134    }
1135
1136    async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> {
1137        let mut conn = self.get_connection().await?;
1138        let storage_key = self.key(&format!("kv:{key}"));
1139
1140        let value: Option<Vec<u8>> = redis::cmd("GET")
1141            .arg(&storage_key)
1142            .query_async(&mut conn)
1143            .await
1144            .map_err(|e| StorageError::operation_failed(format!("Failed to get KV: {e}")))?;
1145
1146        Ok(value)
1147    }
1148
1149    async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
1150        let mut conn = self.get_connection().await?;
1151        let storage_key = self.key(&format!("kv:{key}"));
1152
1153        // PTTL: -2 = no such key, -1 = no expiry, otherwise milliseconds left.
1154        let millis: i64 = redis::cmd("PTTL")
1155            .arg(&storage_key)
1156            .query_async(&mut conn)
1157            .await
1158            .map_err(|e| StorageError::operation_failed(format!("Failed to get KV TTL: {e}")))?;
1159
1160        Ok(u64::try_from(millis)
1161            .ok()
1162            .filter(|millis| *millis > 0)
1163            .map(Duration::from_millis))
1164    }
1165
1166    fn tracks_kv_ttl(&self) -> bool {
1167        true
1168    }
1169
1170    async fn delete_kv(&self, key: &str) -> Result<()> {
1171        let mut conn = self.get_connection().await?;
1172        let storage_key = self.key(&format!("kv:{key}"));
1173
1174        let _: () = redis::cmd("DEL")
1175            .arg(&storage_key)
1176            .query_async(&mut conn)
1177            .await
1178            .map_err(|e| StorageError::operation_failed(format!("Failed to delete KV: {e}")))?;
1179
1180        Ok(())
1181    }
1182
1183    async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> {
1184        let mut conn = self.get_connection().await?;
1185        let pattern = self.key(&format!("kv:{prefix}*"));
1186        let keys: Vec<String> = redis::cmd("KEYS")
1187            .arg(&pattern)
1188            .query_async(&mut conn)
1189            .await
1190            .map_err(|e| StorageError::operation_failed(format!("Failed to list KV keys: {e}")))?;
1191
1192        Ok(keys
1193            .into_iter()
1194            .filter_map(|key| key.strip_prefix(&self.key_prefix).map(str::to_string))
1195            .filter_map(|key| key.strip_prefix("kv:").map(str::to_string))
1196            .collect())
1197    }
1198
1199    async fn cleanup_expired(&self) -> Result<()> {
1200        // Redis handles expiration automatically, so this is a no-op
1201        Ok(())
1202    }
1203
1204    async fn count_active_sessions(&self) -> Result<u64> {
1205        let mut conn = self.get_connection().await?;
1206
1207        // Use KEYS to find all session keys (consider SCAN for production with many keys)
1208        let keys = self.session_keys(&mut conn).await?;
1209        // A session present under both names is one session.
1210        let keys = crate::storage::key_names::without_shadowed_legacy(
1211            keys,
1212            &self.legacy_session_key(""),
1213            &self.key("session_h:"),
1214            "session",
1215        );
1216
1217        // Count only non-expired sessions by checking TTL
1218        let mut active_count = 0u64;
1219        for key in keys {
1220            let ttl: i64 = redis::cmd("TTL")
1221                .arg(&key)
1222                .query_async(&mut conn)
1223                .await
1224                .map_err(|e| StorageError::operation_failed(format!("Failed to check TTL: {e}")))?;
1225
1226            // TTL > 0 means key has expiration and is still active
1227            // TTL = -1 means key has no expiration (active)
1228            // TTL = -2 means key doesn't exist (expired)
1229            if ttl > 0 || ttl == -1 {
1230                active_count += 1;
1231            }
1232        }
1233
1234        Ok(active_count)
1235    }
1236}
1237
1238impl SessionData {
1239    /// Create a new session with consistent timestamps.
1240    ///
1241    /// # Arguments
1242    /// * `session_id` - Unique session identifier (typically a UUID)
1243    /// * `user_id` - Associated user ID
1244    /// * `expires_in` - Session lifetime from now
1245    ///
1246    /// Use [`with_metadata`](SessionData::with_metadata) to attach IP and
1247    /// user-agent information after construction.
1248    ///
1249    /// # Panics
1250    /// If `expires_in` conversion to `chrono::Duration` fails catastrophically.
1251    pub fn new(
1252        session_id: impl Into<String>,
1253        user_id: impl Into<String>,
1254        expires_in: Duration,
1255    ) -> Self {
1256        let now = chrono::Utc::now();
1257
1258        Self {
1259            session_id: session_id.into(),
1260            user_id: user_id.into(),
1261            created_at: now,
1262            expires_at: now
1263                + chrono::Duration::from_std(expires_in).unwrap_or(chrono::Duration::hours(1)),
1264            last_activity: now,
1265            ip_address: None,
1266            user_agent: None,
1267            data: HashMap::new(),
1268        }
1269    }
1270
1271    /// Check if the session has expired.
1272    pub fn is_expired(&self) -> bool {
1273        chrono::Utc::now() > self.expires_at
1274    }
1275
1276    /// Return the remaining lifetime of this session.
1277    ///
1278    /// Returns [`Duration::ZERO`](std::time::Duration::ZERO) when the session
1279    /// has already expired.
1280    pub fn time_until_expiry(&self) -> std::time::Duration {
1281        let remaining = self.expires_at - chrono::Utc::now();
1282        remaining.to_std().unwrap_or(std::time::Duration::ZERO)
1283    }
1284
1285    /// Check if the session is still active (not expired).
1286    pub fn is_active(&self) -> bool {
1287        !self.is_expired()
1288    }
1289
1290    /// Update the last activity timestamp.
1291    pub fn update_activity(&mut self) {
1292        self.last_activity = chrono::Utc::now();
1293    }
1294
1295    /// Set session metadata (IP address and user-agent) in one call.
1296    pub fn with_metadata(mut self, ip_address: Option<String>, user_agent: Option<String>) -> Self {
1297        self.ip_address = ip_address;
1298        self.user_agent = user_agent;
1299        self
1300    }
1301
1302    /// Set the client IP address.
1303    pub fn ip_address(mut self, ip: impl Into<String>) -> Self {
1304        self.ip_address = Some(ip.into());
1305        self
1306    }
1307
1308    /// Set the client user-agent string.
1309    pub fn user_agent(mut self, ua: impl Into<String>) -> Self {
1310        self.user_agent = Some(ua.into());
1311        self
1312    }
1313
1314    /// Add a custom data entry (chainable).
1315    pub fn with_data(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
1316        self.data.insert(key.into(), value);
1317        self
1318    }
1319
1320    /// Add custom data to the session.
1321    pub fn set_data(&mut self, key: impl Into<String>, value: serde_json::Value) {
1322        self.data.insert(key.into(), value);
1323    }
1324
1325    /// Get custom data from the session.
1326    pub fn get_data(&self, key: &str) -> Option<&serde_json::Value> {
1327        self.data.get(key)
1328    }
1329}
1330
1331/// Implementation of AuditStorage for MemoryStorage
1332#[async_trait]
1333impl crate::audit::AuditStorage for MemoryStorage {
1334    async fn store_event(&self, event: &crate::audit::AuditEvent) -> Result<()> {
1335        // Store audit event as JSON in KV storage
1336        let json_data = serde_json::to_vec(event).map_err(|e| {
1337            crate::errors::AuthError::internal(format!("Failed to serialize audit event: {}", e))
1338        })?;
1339
1340        let key = format!("audit_event_{}", event.id);
1341        self.store_kv(&key, &json_data, None).await
1342    }
1343
1344    async fn query_events(
1345        &self,
1346        query: &crate::audit::AuditQuery,
1347    ) -> Result<Vec<crate::audit::AuditEvent>> {
1348        // Simple implementation - in production, this would be more efficient
1349        let all_keys = self.list_kv_keys("audit_event_").await?;
1350        let mut events = Vec::new();
1351
1352        for key in all_keys {
1353            if let Some(data) = self.get_kv(&key).await?
1354                && let Ok(event) = serde_json::from_slice::<crate::audit::AuditEvent>(&data)
1355            {
1356                // Apply filters
1357                let mut include = true;
1358
1359                if let Some(ref time_range) = query.time_range
1360                    && (event.timestamp < time_range.start || event.timestamp > time_range.end)
1361                {
1362                    include = false;
1363                }
1364
1365                if let Some(ref event_types) = query.event_types
1366                    && !event_types.contains(&event.event_type)
1367                {
1368                    include = false;
1369                }
1370
1371                if let Some(ref user_id) = query.user_id
1372                    && event.user_id.as_ref() != Some(user_id)
1373                {
1374                    include = false;
1375                }
1376
1377                if include {
1378                    events.push(event);
1379                }
1380            }
1381        }
1382
1383        // Sort and limit
1384        events.sort_by(|a, b| match query.sort_order {
1385            crate::audit::SortOrder::TimestampAsc => a.timestamp.cmp(&b.timestamp),
1386            crate::audit::SortOrder::TimestampDesc => b.timestamp.cmp(&a.timestamp),
1387            crate::audit::SortOrder::RiskLevelDesc => b.risk_level.cmp(&a.risk_level),
1388        });
1389
1390        if let Some(limit) = query.limit {
1391            events.truncate(limit as usize);
1392        }
1393        Ok(events)
1394    }
1395
1396    async fn get_event(&self, event_id: &str) -> Result<Option<crate::audit::AuditEvent>> {
1397        let key = format!("audit_event_{}", event_id);
1398        if let Some(data) = self.get_kv(&key).await? {
1399            let event = serde_json::from_slice(&data).map_err(|e| {
1400                crate::errors::AuthError::internal(format!(
1401                    "Failed to deserialize audit event: {}",
1402                    e
1403                ))
1404            })?;
1405            Ok(Some(event))
1406        } else {
1407            Ok(None)
1408        }
1409    }
1410
1411    async fn count_events(&self, query: &crate::audit::AuditQuery) -> Result<u64> {
1412        let events = self.query_events(query).await?;
1413        Ok(events.len() as u64)
1414    }
1415
1416    async fn delete_old_events(&self, before: std::time::SystemTime) -> Result<u64> {
1417        let all_keys = self.list_kv_keys("audit_event_").await?;
1418        let mut deleted_count = 0;
1419
1420        for key in all_keys {
1421            if let Some(data) = self.get_kv(&key).await?
1422                && let Ok(event) = serde_json::from_slice::<crate::audit::AuditEvent>(&data)
1423                && event.timestamp < before
1424            {
1425                self.delete_kv(&key).await?;
1426                deleted_count += 1;
1427            }
1428        }
1429
1430        Ok(deleted_count)
1431    }
1432
1433    async fn get_statistics(
1434        &self,
1435        query: &crate::audit::StatsQuery,
1436    ) -> Result<crate::audit::AuditStatistics> {
1437        use std::collections::HashMap;
1438
1439        // Pull all events matching the time range in the query.
1440        let audit_query = crate::audit::AuditQuery::builder()
1441            .time_range(query.time_range.start, query.time_range.end)
1442            .sort_order(crate::audit::SortOrder::TimestampAsc)
1443            .build();
1444        let events = self.query_events(&audit_query).await?;
1445        let total_events = events.len() as u64;
1446
1447        let mut event_type_counts: HashMap<String, u64> = HashMap::new();
1448        let mut risk_level_counts: HashMap<String, u64> = HashMap::new();
1449        let mut outcome_counts: HashMap<String, u64> = HashMap::new();
1450
1451        for event in &events {
1452            *event_type_counts
1453                .entry(format!("{:?}", event.event_type))
1454                .or_insert(0) += 1;
1455            *risk_level_counts
1456                .entry(format!("{:?}", event.risk_level))
1457                .or_insert(0) += 1;
1458            *outcome_counts
1459                .entry(format!("{:?}", event.outcome))
1460                .or_insert(0) += 1;
1461        }
1462
1463        Ok(crate::audit::AuditStatistics {
1464            total_events,
1465            event_type_counts,
1466            risk_level_counts,
1467            outcome_counts,
1468            time_series: Vec::new(),
1469            top_users: Vec::new(),
1470            top_ips: Vec::new(),
1471        })
1472    }
1473}
1474
1475impl MemoryStorage {
1476    /// Helper method to list KV keys with a prefix
1477    async fn list_kv_keys(&self, _prefix: &str) -> Result<Vec<String>> {
1478        Ok(self.inner.list_kv_keys_by_prefix(_prefix))
1479    }
1480}
1481
1482/// Implementation of AuditStorage for `Arc<MemoryStorage>`
1483#[async_trait]
1484impl crate::audit::AuditStorage for Arc<MemoryStorage> {
1485    async fn store_event(&self, event: &crate::audit::AuditEvent) -> Result<()> {
1486        self.as_ref().store_event(event).await
1487    }
1488
1489    async fn query_events(
1490        &self,
1491        query: &crate::audit::AuditQuery,
1492    ) -> Result<Vec<crate::audit::AuditEvent>> {
1493        self.as_ref().query_events(query).await
1494    }
1495
1496    async fn get_event(&self, event_id: &str) -> Result<Option<crate::audit::AuditEvent>> {
1497        self.as_ref().get_event(event_id).await
1498    }
1499
1500    async fn count_events(&self, query: &crate::audit::AuditQuery) -> Result<u64> {
1501        self.as_ref().count_events(query).await
1502    }
1503
1504    async fn delete_old_events(&self, before: std::time::SystemTime) -> Result<u64> {
1505        self.as_ref().delete_old_events(before).await
1506    }
1507
1508    async fn get_statistics(
1509        &self,
1510        query: &crate::audit::StatsQuery,
1511    ) -> Result<crate::audit::AuditStatistics> {
1512        self.as_ref().get_statistics(query).await
1513    }
1514}
1515
1516#[cfg(test)]
1517mod tests {
1518    use super::*;
1519    use crate::tokens::AuthToken;
1520
1521    // ── Token CRUD ──────────────────────────────────────────────────
1522
1523    #[tokio::test]
1524    async fn test_memory_storage() {
1525        let storage = MemoryStorage::new();
1526
1527        let token = AuthToken::new("user123", "token123", Duration::from_secs(3600), "test");
1528
1529        storage.store_token(&token).await.unwrap();
1530
1531        let retrieved = storage.get_token(&token.token_id).await.unwrap().unwrap();
1532        assert_eq!(retrieved.user_id, "user123");
1533
1534        let retrieved = storage
1535            .get_token_by_access_token(&token.access_token)
1536            .await
1537            .unwrap()
1538            .unwrap();
1539        assert_eq!(retrieved.token_id, token.token_id);
1540
1541        let user_tokens = storage.list_user_tokens("user123").await.unwrap();
1542        assert_eq!(user_tokens.len(), 1);
1543
1544        storage.delete_token(&token.token_id).await.unwrap();
1545        let retrieved = storage.get_token(&token.token_id).await.unwrap();
1546        assert!(retrieved.is_none());
1547    }
1548
1549    #[tokio::test]
1550    async fn test_token_update() {
1551        let storage = MemoryStorage::new();
1552        let mut token = AuthToken::new("user1", "access_original", Duration::from_secs(3600), "pw");
1553        storage.store_token(&token).await.unwrap();
1554
1555        token.auth_method = "mfa".to_string();
1556        storage.update_token(&token).await.unwrap();
1557
1558        let retrieved = storage.get_token(&token.token_id).await.unwrap().unwrap();
1559        assert_eq!(retrieved.auth_method, "mfa");
1560    }
1561
1562    #[tokio::test]
1563    async fn test_token_get_nonexistent() {
1564        let storage = MemoryStorage::new();
1565        let result = storage.get_token("nonexistent").await.unwrap();
1566        assert!(result.is_none());
1567
1568        let result = storage
1569            .get_token_by_access_token("nonexistent")
1570            .await
1571            .unwrap();
1572        assert!(result.is_none());
1573    }
1574
1575    #[tokio::test]
1576    async fn test_list_user_tokens_multiple() {
1577        let storage = MemoryStorage::new();
1578        let t1 = AuthToken::new("user_a", "at1", Duration::from_secs(3600), "pw");
1579        let t2 = AuthToken::new("user_a", "at2", Duration::from_secs(3600), "pw");
1580        let t3 = AuthToken::new("user_b", "at3", Duration::from_secs(3600), "pw");
1581
1582        storage.store_token(&t1).await.unwrap();
1583        storage.store_token(&t2).await.unwrap();
1584        storage.store_token(&t3).await.unwrap();
1585
1586        let user_a_tokens = storage.list_user_tokens("user_a").await.unwrap();
1587        assert_eq!(user_a_tokens.len(), 2);
1588
1589        let user_b_tokens = storage.list_user_tokens("user_b").await.unwrap();
1590        assert_eq!(user_b_tokens.len(), 1);
1591
1592        let empty = storage.list_user_tokens("nobody").await.unwrap();
1593        assert!(empty.is_empty());
1594    }
1595
1596    #[tokio::test]
1597    async fn test_store_tokens_bulk() {
1598        let storage = MemoryStorage::new();
1599        let tokens = vec![
1600            AuthToken::new("u1", "a1", Duration::from_secs(3600), "pw"),
1601            AuthToken::new("u2", "a2", Duration::from_secs(3600), "pw"),
1602            AuthToken::new("u3", "a3", Duration::from_secs(3600), "pw"),
1603        ];
1604        let ids: Vec<String> = tokens.iter().map(|t| t.token_id.clone()).collect();
1605
1606        storage.store_tokens_bulk(&tokens).await.unwrap();
1607
1608        for id in &ids {
1609            assert!(storage.get_token(id).await.unwrap().is_some());
1610        }
1611
1612        storage.delete_tokens_bulk(&ids).await.unwrap();
1613
1614        for id in &ids {
1615            assert!(storage.get_token(id).await.unwrap().is_none());
1616        }
1617    }
1618
1619    // ── Session CRUD ────────────────────────────────────────────────
1620
1621    #[tokio::test]
1622    async fn test_session_storage() {
1623        let storage = MemoryStorage::new();
1624
1625        let session = SessionData::new("session123", "user123", Duration::from_secs(3600))
1626            .with_metadata(
1627                Some("192.168.1.1".to_string()),
1628                Some("Test Agent".to_string()),
1629            );
1630
1631        storage
1632            .store_session(&session.session_id, &session)
1633            .await
1634            .unwrap();
1635
1636        let retrieved = storage
1637            .get_session(&session.session_id)
1638            .await
1639            .unwrap()
1640            .unwrap();
1641        assert_eq!(retrieved.user_id, "user123");
1642        assert_eq!(retrieved.ip_address, Some("192.168.1.1".to_string()));
1643
1644        storage.delete_session(&session.session_id).await.unwrap();
1645        let retrieved = storage.get_session(&session.session_id).await.unwrap();
1646        assert!(retrieved.is_none());
1647    }
1648
1649    #[tokio::test]
1650    async fn test_session_get_nonexistent() {
1651        let storage = MemoryStorage::new();
1652        let result = storage.get_session("no_such_session").await.unwrap();
1653        assert!(result.is_none());
1654    }
1655
1656    #[tokio::test]
1657    async fn test_list_user_sessions() {
1658        let storage = MemoryStorage::new();
1659
1660        let s1 = SessionData::new("s1", "alice", Duration::from_secs(3600));
1661        let s2 = SessionData::new("s2", "alice", Duration::from_secs(3600));
1662        let s3 = SessionData::new("s3", "bob", Duration::from_secs(3600));
1663
1664        storage.store_session("s1", &s1).await.unwrap();
1665        storage.store_session("s2", &s2).await.unwrap();
1666        storage.store_session("s3", &s3).await.unwrap();
1667
1668        let alice_sessions = storage.list_user_sessions("alice").await.unwrap();
1669        assert_eq!(alice_sessions.len(), 2);
1670
1671        let bob_sessions = storage.list_user_sessions("bob").await.unwrap();
1672        assert_eq!(bob_sessions.len(), 1);
1673    }
1674
1675    #[tokio::test]
1676    async fn test_count_active_sessions() {
1677        let storage = MemoryStorage::new();
1678
1679        let s1 = SessionData::new("cs1", "u1", Duration::from_secs(3600));
1680        let s2 = SessionData::new("cs2", "u2", Duration::from_secs(3600));
1681        storage.store_session("cs1", &s1).await.unwrap();
1682        storage.store_session("cs2", &s2).await.unwrap();
1683
1684        let count = storage.count_active_sessions().await.unwrap();
1685        assert!(count >= 2);
1686    }
1687
1688    #[tokio::test]
1689    async fn test_store_sessions_bulk() {
1690        let storage = MemoryStorage::new();
1691        let sessions = vec![
1692            (
1693                "bs1".to_string(),
1694                SessionData::new("bs1", "u1", Duration::from_secs(3600)),
1695            ),
1696            (
1697                "bs2".to_string(),
1698                SessionData::new("bs2", "u2", Duration::from_secs(3600)),
1699            ),
1700        ];
1701
1702        storage.store_sessions_bulk(&sessions).await.unwrap();
1703        assert!(storage.get_session("bs1").await.unwrap().is_some());
1704        assert!(storage.get_session("bs2").await.unwrap().is_some());
1705
1706        let ids = vec!["bs1".to_string(), "bs2".to_string()];
1707        storage.delete_sessions_bulk(&ids).await.unwrap();
1708        assert!(storage.get_session("bs1").await.unwrap().is_none());
1709        assert!(storage.get_session("bs2").await.unwrap().is_none());
1710    }
1711
1712    #[tokio::test]
1713    async fn test_session_custom_data() {
1714        let storage = MemoryStorage::new();
1715        let mut session = SessionData::new("sd1", "u1", Duration::from_secs(3600));
1716        session.set_data("theme", serde_json::json!("dark"));
1717        session.set_data("lang", serde_json::json!("en"));
1718
1719        storage.store_session("sd1", &session).await.unwrap();
1720
1721        let retrieved = storage.get_session("sd1").await.unwrap().unwrap();
1722        assert_eq!(
1723            retrieved.get_data("theme"),
1724            Some(&serde_json::json!("dark"))
1725        );
1726        assert_eq!(retrieved.get_data("lang"), Some(&serde_json::json!("en")));
1727        assert_eq!(retrieved.get_data("missing"), None);
1728    }
1729
1730    // ── KV Storage ──────────────────────────────────────────────────
1731
1732    #[tokio::test]
1733    async fn test_kv_storage() {
1734        let storage = MemoryStorage::new();
1735
1736        let key = "test_key";
1737        let value = b"test_value";
1738
1739        storage
1740            .store_kv(key, value, Some(Duration::from_secs(3600)))
1741            .await
1742            .unwrap();
1743
1744        let retrieved = storage.get_kv(key).await.unwrap().unwrap();
1745        assert_eq!(retrieved, value);
1746
1747        storage.delete_kv(key).await.unwrap();
1748        let retrieved = storage.get_kv(key).await.unwrap();
1749        assert!(retrieved.is_none());
1750    }
1751
1752    #[tokio::test]
1753    async fn test_kv_no_ttl() {
1754        let storage = MemoryStorage::new();
1755        storage
1756            .store_kv("persistent", b"forever", None)
1757            .await
1758            .unwrap();
1759
1760        let retrieved = storage.get_kv("persistent").await.unwrap().unwrap();
1761        assert_eq!(retrieved, b"forever");
1762    }
1763
1764    #[tokio::test]
1765    async fn test_kv_overwrite() {
1766        let storage = MemoryStorage::new();
1767        storage
1768            .store_kv("k1", b"v1", Some(Duration::from_secs(3600)))
1769            .await
1770            .unwrap();
1771        storage
1772            .store_kv("k1", b"v2", Some(Duration::from_secs(3600)))
1773            .await
1774            .unwrap();
1775
1776        let retrieved = storage.get_kv("k1").await.unwrap().unwrap();
1777        assert_eq!(retrieved, b"v2");
1778    }
1779
1780    #[tokio::test]
1781    async fn test_kv_get_nonexistent() {
1782        let storage = MemoryStorage::new();
1783        let result = storage.get_kv("no_such_key").await.unwrap();
1784        assert!(result.is_none());
1785    }
1786
1787    #[tokio::test]
1788    async fn test_kv_list_keys_prefix() {
1789        let storage = MemoryStorage::new();
1790        storage
1791            .store_kv("user:1:name", b"alice", None)
1792            .await
1793            .unwrap();
1794        storage
1795            .store_kv("user:1:email", b"alice@x.com", None)
1796            .await
1797            .unwrap();
1798        storage.store_kv("user:2:name", b"bob", None).await.unwrap();
1799        storage
1800            .store_kv("session:abc", b"data", None)
1801            .await
1802            .unwrap();
1803
1804        let user1_keys = storage.list_kv_keys("user:1:").await.unwrap();
1805        assert_eq!(user1_keys.len(), 2);
1806
1807        let all_user_keys = storage.list_kv_keys("user:").await.unwrap();
1808        assert_eq!(all_user_keys.len(), 3);
1809
1810        let session_keys = storage.list_kv_keys("session:").await.unwrap();
1811        assert_eq!(session_keys.len(), 1);
1812
1813        let empty = storage.list_kv_keys("nonexistent:").await.unwrap();
1814        assert!(empty.is_empty());
1815    }
1816
1817    #[tokio::test]
1818    async fn test_kv_binary_data() {
1819        let storage = MemoryStorage::new();
1820        let binary = vec![0u8, 1, 2, 255, 254, 253, 0, 128];
1821        storage.store_kv("binary_key", &binary, None).await.unwrap();
1822
1823        let retrieved = storage.get_kv("binary_key").await.unwrap().unwrap();
1824        assert_eq!(retrieved, binary);
1825    }
1826
1827    // ── Cleanup ──────────────────────────────────────────────────────
1828
1829    #[tokio::test]
1830    async fn test_cleanup_expired() {
1831        let storage = MemoryStorage::new();
1832
1833        // Store a KV entry with a very short TTL (already expired by the time
1834        // cleanup runs because DashMap wraps its own expiry clock).
1835        // Note: MemoryStorage cleanup uses TimestampedToken's own expires_at
1836        // (derived from default_ttl), NOT AuthToken.expires_at. We test KV
1837        // cleanup because it respects TTLs directly.
1838        storage
1839            .store_kv("expire_me", b"val", Some(Duration::from_secs(0)))
1840            .await
1841            .unwrap();
1842        storage
1843            .store_kv("keep_me", b"val", Some(Duration::from_secs(3600)))
1844            .await
1845            .unwrap();
1846
1847        // Give a tiny window for the zero-TTL entry to register as expired
1848        tokio::time::sleep(Duration::from_millis(10)).await;
1849
1850        storage.cleanup_expired().await.unwrap();
1851
1852        // Zero-TTL entry should be cleaned up, valid entry remains
1853        assert!(storage.get_kv("expire_me").await.unwrap().is_none());
1854        assert!(storage.get_kv("keep_me").await.unwrap().is_some());
1855    }
1856
1857    // ── Session expiration ──────────────────────────────────────────
1858
1859    #[tokio::test]
1860    async fn test_session_is_expired() {
1861        let mut session = SessionData::new("exp1", "u1", Duration::from_secs(3600));
1862        assert!(!session.is_expired());
1863
1864        session.expires_at = chrono::Utc::now() - chrono::Duration::seconds(1);
1865        assert!(session.is_expired());
1866    }
1867
1868    #[tokio::test]
1869    async fn test_session_update_activity() {
1870        let mut session = SessionData::new("act1", "u1", Duration::from_secs(3600));
1871        let first_activity = session.last_activity;
1872        // Small delay to ensure timestamp changes
1873        session.update_activity();
1874        assert!(session.last_activity >= first_activity);
1875    }
1876
1877    // ── Token upsert semantics ──────────────────────────────────────
1878
1879    #[tokio::test]
1880    async fn test_token_store_twice_overwrites_primary() {
1881        let storage = MemoryStorage::new();
1882        let token = AuthToken::new("u1", "at1", Duration::from_secs(3600), "pw");
1883        let token_id = token.token_id.clone();
1884
1885        storage.store_token(&token).await.unwrap();
1886        storage.store_token(&token).await.unwrap();
1887
1888        // Primary DashMap uses insert() so only one entry with this token_id exists.
1889        let got = storage.get_token(&token_id).await.unwrap();
1890        assert!(got.is_some());
1891    }
1892
1893    // ── Delete idempotency ──────────────────────────────────────────
1894
1895    #[tokio::test]
1896    async fn test_delete_nonexistent_token() {
1897        let storage = MemoryStorage::new();
1898        // Deleting a key that doesn't exist should not error
1899        let result = storage.delete_token("nope").await;
1900        assert!(result.is_ok());
1901    }
1902
1903    #[tokio::test]
1904    async fn test_delete_nonexistent_session() {
1905        let storage = MemoryStorage::new();
1906        let result = storage.delete_session("nope").await;
1907        assert!(result.is_ok());
1908    }
1909
1910    #[tokio::test]
1911    async fn test_delete_nonexistent_kv() {
1912        let storage = MemoryStorage::new();
1913        let result = storage.delete_kv("nope").await;
1914        assert!(result.is_ok());
1915    }
1916}