pas-external 4.0.1

//! Building blocks for `sv` claim validation
//! (STANDARDS_AUTH_INVALIDATION §5).
//!
//! In 4.0.0 the validator itself moved into the middleware layer
//! (see [`SvAwareSessionResolver`](crate::middleware::SvAwareSessionResolver))
//! so consumers get sv enforcement by default. This module hosts the
//! reusable primitives:
//!
//! - [`SessionVersionCache`] — pluggable cache trait (default impl:
//!   in-memory [`MemorySessionVersionCache`], 60 s TTL). Consumers with
//!   shared substrates (KVRocks, Redis) can implement this trait to
//!   converge break-glass across pods within network RTT instead of
//!   waiting for the per-pod TTL.
//! - [`SV_CACHE_KEY_PREFIX`] / [`SV_CACHE_TTL`] — the cache contract
//!   constants. Match PAS's `crates/ppoppo-token::sv_cache_key` so a
//!   custom KVRocks cache adapter can read the same key namespace as
//!   PCS chat-auth.
//!
//! See [`SvAwareSessionResolver`](crate::middleware::SvAwareSessionResolver)
//! for the resolver entry point.

use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant};

use async_trait::async_trait;
use tokio::sync::RwLock;

/// Namespace prefix for cache keys. Matches chat-auth and is_admin caches.
pub const SV_CACHE_KEY_PREFIX: &str = "sv:";

/// TTL per `paseto-sv-claim.md §R5`. 60 s, non-configurable by design.
pub const SV_CACHE_TTL: Duration = Duration::from_secs(60);

/// Cache abstraction for `sv:{ppnum_id}` lookups.
///
/// Default implementation is [`MemorySessionVersionCache`]. Consumers
/// that already run KVRocks/Redis can write their own adapter — the
/// `get` / `set` contract is minimal.
///
/// `get` returns `None` on cache miss OR any transient backend error.
/// `set` is best-effort and swallows failures internally (a failed set
/// only costs us one extra fetch on the next validate).
#[async_trait]
pub trait SessionVersionCache: Send + Sync {
    async fn get(&self, key: &str) -> Option<i64>;
    async fn set(&self, key: &str, sv: i64, ttl: Duration);
}

/// In-memory [`SessionVersionCache`]. Default choice for SDK consumers.
///
/// `tokio::sync::RwLock<HashMap<String, (sv, Instant)>>` with lazy
/// eviction on read: entries past their TTL are treated as miss.
/// Production consumers with many pods may want to plug in a shared
/// cache (Redis, KVRocks) so a break-glass on one pod converges on all
/// pods within the same 60 s window; the in-memory default is per-pod.
pub struct MemorySessionVersionCache {
    inner: Arc<RwLock<HashMap<String, (i64, Instant)>>>,
}

impl MemorySessionVersionCache {
    #[must_use]
    pub fn new() -> Self {
        Self {
            inner: Arc::new(RwLock::new(HashMap::new())),
        }
    }
}

impl Default for MemorySessionVersionCache {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl SessionVersionCache for MemorySessionVersionCache {
    async fn get(&self, key: &str) -> Option<i64> {
        let guard = self.inner.read().await;
        let (sv, written_at) = guard.get(key)?;
        if written_at.elapsed() >= SV_CACHE_TTL {
            return None;
        }
        Some(*sv)
    }

    async fn set(&self, key: &str, sv: i64, _ttl: Duration) {
        // TTL is governed by the SV_CACHE_TTL constant; ignore the param
        // so callers can't accidentally drift this substrate's TTL away
        // from the contract.
        let mut guard = self.inner.write().await;
        guard.insert(key.to_string(), (sv, Instant::now()));
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn memory_cache_respects_ttl() {
        // Exercises MemorySessionVersionCache's lazy-eviction-on-read.
        // Can't literally advance wall clock, so this only proves that
        // within-TTL reads hit — the expiry branch is covered by
        // construction (if written_at.elapsed() >= SV_CACHE_TTL → None).
        let cache = MemorySessionVersionCache::new();
        cache.set("sv:abc", 42, SV_CACHE_TTL).await;
        assert_eq!(cache.get("sv:abc").await, Some(42));
        assert_eq!(cache.get("sv:missing").await, None);
    }

    #[tokio::test]
    async fn memory_cache_overwrite() {
        // A second set with the same key replaces the prior value.
        // Exercises the SvAwareSessionResolver refresh path that updates
        // the cache after picking up a newer sv.
        let cache = MemorySessionVersionCache::new();
        cache.set("sv:xyz", 1, SV_CACHE_TTL).await;
        cache.set("sv:xyz", 2, SV_CACHE_TTL).await;
        assert_eq!(cache.get("sv:xyz").await, Some(2));
    }
}