meerkat-core 0.8.31

//! TokenStore trait + PersistedTokens/TokenKey types + RefreshCoordinator.
//!
//! Moved from `meerkat-providers::auth_store` (B2 split, 2026-04-18) so
//! the trait surface is reachable without heavy-IO dependencies.
//! Concrete backends (File/Keyring/Auto/Ephemeral/InMemory/FileLock)
//! live in `meerkat-auth-core::auth_store`.

use async_trait::async_trait;
use chrono::{DateTime, Utc};
use futures::future::BoxFuture;
use serde::{Deserialize, Serialize};
use thiserror::Error;

use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use crate::connection::{
    AuthBindingRef, AuthCredentialIdentity, BindingId, CredentialAccountId, IdentityError,
    ProfileId, RealmId,
};

/// Key for a persisted token bundle.
///
/// Binding-backed keys retain their historical serialized representation.
/// Account-backed keys let several provider routes share one durable
/// credential without duplicating lifecycle authority.
#[derive(Clone, Debug, Eq, PartialEq, Hash, Serialize, Ord, PartialOrd)]
#[serde(transparent)]
pub struct TokenKey(AuthCredentialIdentity);

impl<'de> Deserialize<'de> for TokenKey {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let identity = AuthCredentialIdentity::deserialize(deserializer)?;
        Ok(Self::from_credential_identity(&identity))
    }
}

impl TokenKey {
    /// Construct a token key from already-typed atoms. The primary
    /// constructor — call sites that have the typed forms (e.g. from
    /// `AuthBindingRef.realm` / `AuthBindingRef.binding`) use this
    /// directly. Raw-string call sites build the atoms at their CLI /
    /// wire boundary via `RealmId::parse` / `BindingId::parse` and
    /// fold the resulting `Result<TokenKey, IdentityError>` into their
    /// ambient error handling.
    pub fn new(realm: RealmId, binding: BindingId) -> Self {
        Self(AuthCredentialIdentity::Binding(AuthBindingRef {
            realm,
            binding,
            profile: None,
            origin: crate::connection::BindingOrigin::Configured,
        }))
    }

    pub fn new_with_profile(
        realm: RealmId,
        binding: BindingId,
        profile: Option<ProfileId>,
    ) -> Self {
        Self(AuthCredentialIdentity::Binding(AuthBindingRef {
            realm,
            binding,
            profile,
            origin: crate::connection::BindingOrigin::Configured,
        }))
    }

    pub fn from_auth_binding(auth_binding: &AuthBindingRef) -> Self {
        Self(AuthCredentialIdentity::from_auth_binding(auth_binding))
    }

    pub fn from_credential_identity(identity: &AuthCredentialIdentity) -> Self {
        Self(identity.normalized_for_credential_storage())
    }

    pub fn credential_identity(&self) -> &AuthCredentialIdentity {
        &self.0
    }

    pub fn realm(&self) -> &RealmId {
        self.0.realm()
    }

    pub fn binding(&self) -> Option<&BindingId> {
        self.0.binding()
    }

    pub fn profile(&self) -> Option<&ProfileId> {
        self.0.profile()
    }

    pub fn account(&self) -> Option<&CredentialAccountId> {
        self.0.account()
    }

    /// Construct a token key from raw strings, validating each component
    /// against the slug grammar enforced by
    /// `meerkat_core::connection::{RealmId,BindingId}::parse`. This is
    /// the right entry point for callers that only have flat-string
    /// input — the CLI `--auth-binding` parser, wire-layer handlers,
    /// test fixtures.
    pub fn parse(realm: impl AsRef<str>, binding: impl AsRef<str>) -> Result<Self, IdentityError> {
        Self::parse_with_profile(realm, binding, None::<&str>)
    }

    pub fn parse_with_profile(
        realm: impl AsRef<str>,
        binding: impl AsRef<str>,
        profile: Option<impl AsRef<str>>,
    ) -> Result<Self, IdentityError> {
        Ok(Self::new_with_profile(
            RealmId::parse(realm.as_ref())?,
            BindingId::parse(binding.as_ref())?,
            profile
                .map(|profile| ProfileId::parse(profile.as_ref()))
                .transpose()?,
        ))
    }

    /// The flat account identifier used by OS keyrings.
    ///
    /// Default binding credentials preserve the legacy format:
    /// `<realm>:<binding>`. Profile override credentials include the
    /// canonical override atom: `<realm>:<binding>:<profile>`. Shared accounts
    /// use `<realm>:account~<account>`, where `~` is outside the binding/profile
    /// slug grammar and therefore cannot collide with a legacy key.
    ///
    /// The default credential format stays identical to the pre-profile-key
    /// output; this method is the source of truth for the keyring
    /// `service:account` convention, so the default branch must preserve that
    /// output byte-for-byte to keep existing OAuth credentials reachable.
    pub fn keyring_account(&self) -> String {
        match self.credential_identity() {
            AuthCredentialIdentity::Binding(binding) => match &binding.profile {
                Some(profile) => {
                    format!("{}:{}:{}", binding.realm, binding.binding, profile)
                }
                None => format!("{}:{}", binding.realm, binding.binding),
            },
            AuthCredentialIdentity::Account(account) => {
                format!("{}:account~{}", account.realm, account.account)
            }
        }
    }

    /// Path-safe stable component below the owning realm directory.
    pub fn storage_stem(&self) -> String {
        match self.credential_identity() {
            AuthCredentialIdentity::Binding(binding) => match &binding.profile {
                Some(profile) => format!("{}@{}", binding.binding, profile),
                None => binding.binding.to_string(),
            },
            AuthCredentialIdentity::Account(account) => format!("account~{}", account.account),
        }
    }
}

impl std::fmt::Display for TokenKey {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(formatter)
    }
}

/// Kind of credential material persisted.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PersistedAuthMode {
    ApiKey,
    StaticBearer,
    ChatgptOauth,
    ClaudeAiOauth,
    OauthToApiKey,
    GoogleOauth,
    GithubCopilotOauth,
    Adc,
    ComputeAdc,
    Bedrock,
    Vertex,
    Foundry,
    McpOauth,
    ExternalTokens,
    ExternalAuthorizer,
    Command,
}

/// Serializable token bundle.
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct PersistedTokens {
    pub auth_mode: PersistedAuthMode,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub primary_secret: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub refresh_token: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub id_token: Option<String>,
    #[serde(
        skip_serializing_if = "Option::is_none",
        default,
        with = "chrono::serde::ts_seconds_option"
    )]
    pub expires_at: Option<DateTime<Utc>>,
    #[serde(
        skip_serializing_if = "Option::is_none",
        default,
        with = "chrono::serde::ts_seconds_option"
    )]
    pub last_refresh: Option<DateTime<Utc>>,
    #[serde(default)]
    pub scopes: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub account_id: Option<String>,
    #[serde(default)]
    pub metadata: serde_json::Value,
}

impl PersistedTokens {
    pub fn api_key(secret: impl Into<String>) -> Self {
        Self {
            auth_mode: PersistedAuthMode::ApiKey,
            primary_secret: Some(secret.into()),
            refresh_token: None,
            id_token: None,
            expires_at: None,
            last_refresh: None,
            scopes: Vec::new(),
            account_id: None,
            metadata: serde_json::Value::Null,
        }
    }

    pub fn static_bearer(token: impl Into<String>) -> Self {
        Self {
            auth_mode: PersistedAuthMode::StaticBearer,
            primary_secret: Some(token.into()),
            refresh_token: None,
            id_token: None,
            expires_at: None,
            last_refresh: None,
            scopes: Vec::new(),
            account_id: None,
            metadata: serde_json::Value::Null,
        }
    }
}

/// Errors from the token-store layer.
#[derive(Debug, Error)]
pub enum TokenStoreError {
    #[error("io error: {0}")]
    Io(String),
    #[error("serialization error: {0}")]
    Serde(String),
    #[error("keyring backend unavailable: {0}")]
    KeyringUnavailable(String),
    #[error("no credentials found for {realm}:{binding}")]
    NotFound { realm: String, binding: String },
    #[error("permission denied: {0}")]
    PermissionDenied(String),
    #[error("backend unavailable: {0}")]
    Unavailable(String),
}

#[cfg(not(target_arch = "wasm32"))]
impl From<std::io::Error> for TokenStoreError {
    fn from(e: std::io::Error) -> Self {
        match e.kind() {
            std::io::ErrorKind::PermissionDenied => Self::PermissionDenied(e.to_string()),
            std::io::ErrorKind::NotFound => Self::Io(e.to_string()),
            _ => Self::Io(e.to_string()),
        }
    }
}

impl From<serde_json::Error> for TokenStoreError {
    fn from(e: serde_json::Error) -> Self {
        Self::Serde(e.to_string())
    }
}

/// Cross-process-safe persistence for tokens.
///
/// # Vault property: the durable lifecycle marker is the proof-of-acquisition
///
/// `TokenStore` persists credential *material*; the AuthMachine lease owns the
/// credential *lifecycle*. The bridge between the two is the durable lifecycle
/// marker embedded in [`PersistedTokens::metadata`] by
/// `mark_tokens_lifecycle_published_for_transition`: it is stamped from an
/// AuthMachine acquisition transition and is the only durable proof that the
/// machine recorded the acquisition.
///
/// Writers MUST follow acquire-first ordering: acquire the AuthMachine lease
/// (`publish_token_lifecycle_acquired`), stamp the marker from the returned
/// transition, then perform a single `save` of the marked tokens. Unmarked
/// token bytes must never be persisted — on a crash the durable record either
/// carries the marker or does not exist, so no orphan window is
/// representable.
///
/// Readers MUST only use persisted tokens after marker validation through the
/// lifecycle restore path (`restore_marked_token_lifecycle` /
/// `rehydrate_marked_tokens_for_status`) and the AuthMachine admission gate
/// (`resolve_credential_use_admission` in the resolver). A persisted token
/// without a valid marker is dead data: no acquisition was recorded for it,
/// and it must be rejected, never silently adopted.
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait TokenStore: Send + Sync {
    async fn load(&self, key: &TokenKey) -> Result<Option<PersistedTokens>, TokenStoreError>;
    async fn save(&self, key: &TokenKey, tokens: &PersistedTokens) -> Result<(), TokenStoreError>;
    async fn clear(&self, key: &TokenKey) -> Result<(), TokenStoreError>;
    async fn list(&self) -> Result<Vec<TokenKey>, TokenStoreError>;
    fn backend_name(&self) -> &'static str;
}

/// Errors raised by the refresh coordinator.
#[derive(Clone, Debug, Error)]
pub enum RefreshError {
    #[error("refresh function failed: {0}")]
    Refresh(String),
    #[error("refresh function failed: {message}")]
    Observed {
        message: String,
        observation: RefreshFailureObservation,
    },
    #[error("refresh function failed: {message}")]
    Classified {
        message: String,
        observation: RefreshFailureObservation,
        disposition: RefreshFailureDisposition,
    },
    #[error("refresh requires interactive reauthorization: {0}")]
    ReauthRequired(String),
    #[error("refresh in progress was cancelled")]
    Cancelled,
    #[error("cross-process lock acquisition failed: {0}")]
    LockFailed(String),
    #[error("durable credential terminal commit failed: {message}")]
    DurableTerminalCommit {
        message: String,
        observation: RefreshFailureObservation,
        disposition: RefreshFailureDisposition,
    },
}

/// Machine-issued classification of a typed refresh-failure observation.
///
/// AuthMachine is the semantic owner of this verdict. Provider and persistence
/// shells may mirror it for durable ordering and public error projection, but
/// must never construct it by re-evaluating raw HTTP or OAuth fields.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum RefreshFailureDisposition {
    /// The refresh may be retried after returning the lease to Expiring.
    Transient,
    /// The credential is terminally unusable and interactive authorization is
    /// required.
    ReauthRequired,
}

/// Typed boundary evidence reported to AuthMachine after a refresh failure.
///
/// This is not a lifecycle classification.  It records facts the provider
/// boundary actually observed; AuthMachine owns the semantic permanent vs.
/// transient transition decision.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct RefreshFailureObservation {
    pub http_status: Option<u64>,
    pub oauth_error_code: Option<String>,
    pub local_credential_unusable: bool,
}

impl RefreshFailureObservation {
    pub fn transient() -> Self {
        Self::default()
    }

    pub fn http_status(status: u16) -> Self {
        Self {
            http_status: Some(u64::from(status)),
            ..Self::default()
        }
    }

    pub fn oauth_token_endpoint(status: u16, oauth_error_code: Option<String>) -> Self {
        Self {
            http_status: Some(u64::from(status)),
            oauth_error_code,
            ..Self::default()
        }
    }

    pub fn oauth_error_code(code: impl Into<String>) -> Self {
        Self {
            oauth_error_code: Some(code.into()),
            ..Self::default()
        }
    }

    pub fn local_credential_unusable() -> Self {
        Self {
            local_credential_unusable: true,
            ..Self::default()
        }
    }
}

impl RefreshError {
    pub fn observation(&self) -> RefreshFailureObservation {
        match self {
            Self::Observed { observation, .. }
            | Self::Classified { observation, .. }
            | Self::DurableTerminalCommit { observation, .. } => observation.clone(),
            Self::ReauthRequired(_) => RefreshFailureObservation::local_credential_unusable(),
            Self::Refresh(_) | Self::Cancelled | Self::LockFailed(_) => {
                RefreshFailureObservation::transient()
            }
        }
    }

    /// Return only a disposition issued by AuthMachine's generated classifier.
    /// Unclassified provider errors deliberately return `None` rather than
    /// re-deriving policy from their observation fields.
    pub fn refresh_failure_disposition(&self) -> Option<RefreshFailureDisposition> {
        match self {
            Self::Classified { disposition, .. }
            | Self::DurableTerminalCommit { disposition, .. } => Some(*disposition),
            Self::Refresh(_)
            | Self::Observed { .. }
            | Self::ReauthRequired(_)
            | Self::Cancelled
            | Self::LockFailed(_) => None,
        }
    }
}

/// Boxed refresh closure.
pub type RefreshFn =
    Box<dyn FnOnce() -> BoxFuture<'static, Result<PersistedTokens, RefreshError>> + Send + 'static>;

/// Errors raised while serializing one durable credential mutation.
///
/// Refresh classification remains AuthMachine-owned. This error only describes
/// the mechanics of entering and completing the shared mutation transaction
/// used by refresh and interactive credential replacement.
#[derive(Clone, Debug, Error)]
pub enum CredentialMutationError {
    #[error("credential mutation failed: {0}")]
    Operation(String),
    #[error("credential token-store mutation failed: {0}")]
    TokenStore(String),
    #[error("credential lifecycle mutation failed: {0}")]
    AuthLifecycle(String),
    #[error("credential mutation was cancelled")]
    Cancelled,
    #[error("cross-process credential mutation lock acquisition failed: {0}")]
    LockFailed(String),
}

/// Typed durable result of one exclusive credential mutation.
///
/// Refresh and credential replacement publish the exact persisted token bytes;
/// logout/profile deletion publish the absence of durable credentials. Keeping
/// both outcomes in the coordinator contract lets every mutation share the
/// same per-key cross-process transaction without inventing sentinel tokens or
/// a second locking seam.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum CredentialMutationOutcome {
    Persisted(PersistedTokens),
    Cleared,
}

/// Boxed non-coalescing credential mutation closure.
pub type CredentialMutationFn = Box<
    dyn FnOnce() -> BoxFuture<'static, Result<CredentialMutationOutcome, CredentialMutationError>>
        + Send
        + 'static,
>;

/// Coordinator for token-refresh calls. Implementations coalesce
/// concurrent calls for the same `TokenKey`.
#[async_trait]
pub trait RefreshCoordinator: Send + Sync {
    /// Run one per-key credential mutation under the coordinator's in-process
    /// and, when configured, cross-process exclusion boundary.
    ///
    /// Unlike refresh calls, distinct mutations are never coalesced: every
    /// closure runs exactly once after the prior transaction releases the key.
    async fn with_exclusive_mutation(
        &self,
        key: TokenKey,
        mutation_fn: CredentialMutationFn,
    ) -> Result<CredentialMutationOutcome, CredentialMutationError>;

    async fn with_refresh(
        &self,
        key: TokenKey,
        refresh_fn: RefreshFn,
    ) -> Result<PersistedTokens, RefreshError>;

    async fn with_forced_refresh(
        &self,
        key: TokenKey,
        refresh_fn: RefreshFn,
    ) -> Result<PersistedTokens, RefreshError> {
        self.with_refresh(key, refresh_fn).await
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
mod tests {
    use super::*;
    use crate::{CredentialAccountRef, connection::BindingOrigin};

    #[test]
    fn binding_key_serialization_remains_legacy_compatible() {
        let key = TokenKey::from_auth_binding(&AuthBindingRef {
            realm: RealmId::parse("global").expect("valid realm"),
            binding: BindingId::parse("openai").expect("valid binding"),
            profile: None,
            origin: BindingOrigin::Configured,
        });
        assert_eq!(
            serde_json::to_value(&key).expect("serialize"),
            serde_json::json!({"realm": "global", "binding": "openai"})
        );
        assert_eq!(
            serde_json::from_value::<TokenKey>(
                serde_json::json!({"realm": "global", "binding": "openai"})
            )
            .expect("deserialize legacy key"),
            key
        );
        let synthetic = TokenKey::from_auth_binding(&AuthBindingRef {
            realm: RealmId::parse("global").expect("valid realm"),
            binding: BindingId::parse("openai").expect("valid binding"),
            profile: None,
            origin: BindingOrigin::SyntheticEnvDefault,
        });
        assert_eq!(
            synthetic, key,
            "route provenance is not credential identity"
        );
    }

    #[test]
    fn account_keys_have_disjoint_storage_names() {
        let identity = AuthCredentialIdentity::Account(CredentialAccountRef {
            realm: RealmId::parse("global").expect("valid realm"),
            account: CredentialAccountId::parse("github_copilot").expect("valid account"),
        });
        let key = TokenKey::from_credential_identity(&identity);
        assert_eq!(key.storage_stem(), "account~github_copilot");
        assert_eq!(key.keyring_account(), "global:account~github_copilot");
        assert_eq!(
            serde_json::from_value::<TokenKey>(
                serde_json::to_value(&key).expect("serialize account key")
            )
            .expect("deserialize account key"),
            key
        );
    }
}

/// Complete provider-auth persistence capability.
///
/// Rotating provider credentials are only safe when their vault and mutation
/// authority agree. Keeping the [`TokenStore`] and [`RefreshCoordinator`] in
/// one value makes that pairing an invariant of provider-resolution and
/// factory composition instead of a convention reconstructed by each caller.
/// Native persisted backends construct this value from one backend decision;
/// ephemeral hosts and tests must pair their process-local store and
/// coordinator explicitly through [`Self::new`].
static NEXT_PROVIDER_AUTH_PERSISTENCE_ID: AtomicU64 = AtomicU64::new(1);

/// Process-local identity of one token-vault and mutation-authority pairing.
///
/// Clones retain the same identity. Independently constructed persistence
/// capabilities never share derived credential caches, even when they contain
/// the same logical token key and lifecycle generation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ProviderAuthPersistenceId(u64);

impl ProviderAuthPersistenceId {
    fn next() -> Self {
        Self(NEXT_PROVIDER_AUTH_PERSISTENCE_ID.fetch_add(1, Ordering::Relaxed))
    }
}

#[derive(Clone)]
pub struct ProviderAuthPersistence {
    authority_id: ProviderAuthPersistenceId,
    token_store: Arc<dyn TokenStore>,
    refresh_coordinator: Arc<dyn RefreshCoordinator>,
}

impl ProviderAuthPersistence {
    /// Pair one token vault with the authority that serializes its mutations.
    pub fn new(
        token_store: Arc<dyn TokenStore>,
        refresh_coordinator: Arc<dyn RefreshCoordinator>,
    ) -> Self {
        Self {
            authority_id: ProviderAuthPersistenceId::next(),
            token_store,
            refresh_coordinator,
        }
    }

    pub fn authority_id(&self) -> ProviderAuthPersistenceId {
        self.authority_id
    }

    pub fn token_store(&self) -> Arc<dyn TokenStore> {
        Arc::clone(&self.token_store)
    }

    pub fn refresh_coordinator(&self) -> Arc<dyn RefreshCoordinator> {
        Arc::clone(&self.refresh_coordinator)
    }
}