secretspec 0.12.0

//! # Provider System
//!
//! The provider module implements a trait-based plugin architecture for managing secrets
//! across different storage backends. Providers handle the actual storage and retrieval
//! of secrets, supporting everything from local files to cloud-based secret managers.
//!
//! ## Architecture
//!
//! The provider system is built around the [`Provider`] trait, which defines a common
//! interface for all storage backends. Each provider implementation handles:
//!
//! - Profile-aware storage (e.g., development vs production secrets)
//! - Project isolation (secrets are namespaced by project)
//! - Optional write support (some providers are read-only)
//!
//! ## Available Providers
//!
//! - [`KeyringProvider`]: System keyring integration (default)
//! - [`DotEnvProvider`]: `.env` file support
//! - [`EnvProvider`]: Environment variables (read-only)
//! - [`OnePasswordProvider`]: OnePassword integration
//! - [`LastPassProvider`]: LastPass integration
//!
//! ## URI-Based Configuration
//!
//! Providers support URI-based configuration for flexibility:
//!
//! ```text
//! keyring://
//! dotenv://.env.production
//! onepassword://vault/items
//! lastpass://folder
//! ```
//!
//! ## Example
//!
//! ```rust,ignore
//! use secretspec::provider::Provider;
//! use std::convert::TryFrom;
//!
//! // Create a provider from a URI string
//! let provider = Box::<dyn Provider>::try_from("keyring://")?;
//!
//! // Store a secret
//! provider.set("myproject", "API_KEY", "secret123", "production")?;
//!
//! // Retrieve a secret
//! if let Some(value) = provider.get("myproject", "API_KEY", "production")? {
//!     println!("API_KEY: {}", value);
//! }
//! ```

use crate::{Result, SecretSpecError};
use percent_encoding::{AsciiSet, CONTROLS, percent_decode_str, percent_encode};
use secrecy::SecretString;
use std::collections::HashMap;
use std::convert::TryFrom;
use std::sync::OnceLock;
use url::Url;

/// Characters that are invalid in URI hosts but might appear in provider config
/// values like vault names (e.g., 1Password vault "Home Lab").
/// Structural URI delimiters (@, /, :, ?, #) are intentionally excluded so they
/// are preserved during encoding.
pub(crate) const URI_ENCODE_SET: &AsciiSet = &CONTROLS
    .add(b' ')
    .add(b'<')
    .add(b'>')
    .add(b'[')
    .add(b']')
    .add(b'|')
    .add(b'^')
    .add(b'\\');

/// A URL wrapper that automatically percent-decodes all accessors.
///
/// Providers receive `&ProviderUrl` instead of `&Url`, ensuring they always
/// get decoded values (e.g., `"Home Lab"` instead of `"Home%20Lab"`).
///
/// **Limitation:** Structural URI delimiters (`@`, `/`, `:`, `?`, `#`) are
/// never encoded, so they cannot appear literally in provider config values
/// like vault or folder names. For example, a vault named `"My@Vault"` would
/// be misinterpreted as a username/host separator.
pub(crate) struct ProviderUrl(Url);

impl ProviderUrl {
    pub fn new(url: Url) -> Self {
        Self(url)
    }

    pub fn scheme(&self) -> &str {
        self.0.scheme()
    }

    pub fn host(&self) -> Option<String> {
        self.0
            .host_str()
            .map(|h| percent_decode_str(h).decode_utf8_lossy().into_owned())
    }

    pub fn username(&self) -> String {
        percent_decode_str(self.0.username())
            .decode_utf8_lossy()
            .into_owned()
    }

    pub fn password(&self) -> Option<String> {
        self.0
            .password()
            .map(|p| percent_decode_str(p).decode_utf8_lossy().into_owned())
    }

    pub fn path(&self) -> String {
        percent_decode_str(self.0.path())
            .decode_utf8_lossy()
            .into_owned()
    }

    pub fn port(&self) -> Option<u16> {
        self.0.port()
    }

    pub fn query_pairs(&self) -> url::form_urlencoded::Parse<'_> {
        self.0.query_pairs()
    }

    /// Percent-encode a value for use in a URI (e.g., in `uri()` methods).
    pub fn encode(value: &str) -> String {
        percent_encode(value.as_bytes(), URI_ENCODE_SET).to_string()
    }
}

/// Executes an async future in a blocking context.
///
/// If already inside a tokio runtime, uses `block_in_place` with the
/// existing runtime handle. Otherwise, creates a new runtime.
#[allow(dead_code)]
pub(crate) fn block_on<F: std::future::Future>(future: F) -> F::Output {
    match tokio::runtime::Handle::try_current() {
        Ok(handle) => tokio::task::block_in_place(|| handle.block_on(future)),
        Err(_) => tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .expect("Failed to create tokio runtime")
            .block_on(future),
    }
}

#[cfg(feature = "awssm")]
pub mod awssm;
#[cfg(feature = "bws")]
pub mod bws;
pub mod dotenv;
pub mod env;
#[cfg(feature = "gcsm")]
pub mod gcsm;
#[cfg(feature = "keyring")]
pub mod keyring;
pub mod lastpass;
pub mod onepassword;
pub mod pass;
pub mod protonpass;
#[cfg(feature = "vault")]
pub mod vault;
#[macro_use]
pub mod macros;

#[cfg(test)]
pub(crate) mod tests;

/// Information about a secret storage provider.
///
/// Contains metadata used for displaying available providers to users,
/// including the provider's name, description, and example URIs.
#[derive(Debug, Clone)]
pub struct ProviderInfo {
    /// The canonical name of the provider (e.g., "keyring", "1password").
    pub name: &'static str,
    /// A human-readable description of what the provider does.
    pub description: &'static str,
    /// Example URIs showing how to configure this provider.
    pub examples: &'static [&'static str],
}

impl ProviderInfo {
    /// Formats the provider information for display, including examples if available.
    ///
    /// # Returns
    ///
    /// A formatted string in one of two formats:
    /// - Without examples: "name: description"
    /// - With examples: "name: description (e.g., example1, example2)"
    ///
    /// # Example
    ///
    /// ```ignore
    /// let info = ProviderInfo {
    ///     name: "onepassword",
    ///     description: "OnePassword password manager",
    ///     examples: &["onepassword://vault", "onepassword://work@Production"],
    /// };
    /// assert_eq!(
    ///     info.display_with_examples(),
    ///     "onepassword: OnePassword password manager (e.g., onepassword://vault, onepassword://work@Production)"
    /// );
    /// ```
    pub fn display_with_examples(&self) -> String {
        if self.examples.is_empty() {
            format!("{}: {}", self.name, self.description)
        } else {
            format!(
                "{}: {} (e.g., {})",
                self.name,
                self.description,
                self.examples.join(", ")
            )
        }
    }
}

/// Macro support types
pub use macros::{PROVIDER_REGISTRY, ProviderRegistration};

/// Returns a list of all available providers with their metadata.
///
/// This includes the provider name, description, and example URIs for each
/// supported provider type.
///
/// # Returns
///
/// A vector of `ProviderInfo` structs containing metadata for each provider.
pub fn providers() -> Vec<ProviderInfo> {
    PROVIDER_REGISTRY
        .iter()
        .map(|reg| reg.info.clone())
        .collect()
}

/// Trait defining the interface for secret storage providers.
///
/// All secret storage backends must implement this trait to integrate with SecretSpec.
/// The trait is designed to be flexible enough to support various storage mechanisms
/// while maintaining a consistent interface.
///
/// # Thread Safety
///
/// Providers must be `Send + Sync` as they may be used across thread boundaries
/// in multi-threaded applications.
///
/// # Profile Support
///
/// Providers should support profile-based secret isolation, allowing different values
/// for the same key across environments (e.g., development, staging, production).
///
/// # Implementation Guidelines
///
/// - Providers should handle their own error cases and return appropriate `Result` types
/// - Storage paths should follow the pattern: `{provider}/{project}/{profile}/{key}`
/// - Providers may choose to be read-only by overriding [`allows_set`](Provider::allows_set)
/// - Provider names should be lowercase and descriptive
pub trait Provider: Send + Sync {
    /// Retrieves a secret value from the provider.
    ///
    /// # Arguments
    ///
    /// * `project` - The project namespace for the secret
    /// * `key` - The secret key/name to retrieve
    /// * `profile` - The profile context (e.g., "default", "production")
    ///
    /// # Returns
    ///
    /// - `Ok(Some(value))` if the secret exists
    /// - `Ok(None)` if the secret doesn't exist
    /// - `Err` if there was an error accessing the provider
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// match provider.get("myapp", "DATABASE_URL", "production")? {
    ///     Some(url) => println!("Database URL: {}", url),
    ///     None => println!("DATABASE_URL not found"),
    /// }
    /// ```
    fn get(&self, project: &str, key: &str, profile: &str) -> Result<Option<SecretString>>;

    /// Stores a secret value in the provider.
    ///
    /// # Arguments
    ///
    /// * `project` - The project namespace for the secret
    /// * `key` - The secret key/name to store
    /// * `value` - The secret value to store
    /// * `profile` - The profile context (e.g., "default", "production")
    ///
    /// # Returns
    ///
    /// - `Ok(())` if the secret was successfully stored
    /// - `Err` if there was an error or the provider is read-only
    ///
    /// # Errors
    ///
    /// This method should return an error if [`allows_set`](Provider::allows_set) returns `false`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// provider.set("myapp", "API_KEY", "secret123", "production")?;
    /// ```
    fn set(&self, project: &str, key: &str, value: &SecretString, profile: &str) -> Result<()>;

    /// Returns whether this provider supports setting values.
    ///
    /// By default, providers are assumed to support writing. Read-only providers
    /// (like environment variables) should override this to return `false`.
    ///
    /// # Returns
    ///
    /// - `true` if the provider supports [`set`](Provider::set) operations
    /// - `false` if the provider is read-only
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// if provider.allows_set() {
    ///     provider.set("myapp", "TOKEN", "value", "default")?;
    /// } else {
    ///     eprintln!("Provider is read-only");
    /// }
    /// ```
    fn allows_set(&self) -> bool {
        true
    }

    /// Returns the name of this provider.
    ///
    /// This should match the name registered with the provider macro.
    fn name(&self) -> &'static str;

    /// Returns the full URI representation of this provider.
    ///
    /// This includes any configuration like vault names, paths, etc.
    /// For example: "onepassword://VaultName" or "dotenv://.env.production"
    ///
    /// # Contract: the returned URI must be credential-free
    ///
    /// The audit log records this URI and the fallback-chain warnings print it,
    /// so it must never contain a secret the user embedded in the source URI
    /// (e.g. a `:password` or service-account token). Reconstruct the URI from
    /// non-secret attribution only — account, profile, namespace, host, path —
    /// and drop any credential, which authentication resolves from the
    /// environment or a token field instead. This contract is enforced for every
    /// registered scheme by `uri_never_echoes_a_userinfo_password` in
    /// `provider::tests`.
    fn uri(&self) -> String;

    /// Records a human-readable reason for the secrets access happening in this
    /// session (e.g. "secretspec run: deploy"), set via [`Secrets::with_reason`].
    ///
    /// Providers that support audit logging use this; for example the Proton Pass
    /// provider forwards it to `pass-cli` agent sessions, which require a reason
    /// for every audited item operation. The default implementation ignores it.
    ///
    /// Takes `&self` (relying on interior mutability) so it can be applied after
    /// the provider is wrapped in an `Arc` (as preflight-enabled providers are).
    ///
    /// [`Secrets::with_reason`]: crate::Secrets::with_reason
    fn set_reason(&self, _reason: Option<String>) {}

    /// Discovers and returns all secrets available in this provider.
    ///
    /// This method is used to introspect the provider and find all available secrets.
    /// It's particularly useful for importing secrets from external sources.
    ///
    /// # Returns
    ///
    /// A HashMap where keys are secret names and values are `Secret` configurations.
    /// The default implementation returns an empty map, indicating the provider
    /// doesn't support reflection.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// let secrets = provider.reflect()?;
    /// for (name, secret) in secrets {
    ///     println!("Found secret: {} = {:?}", name, secret);
    /// }
    /// ```
    fn reflect(&self) -> Result<HashMap<String, crate::config::Secret>> {
        Err(SecretSpecError::ProviderOperationFailed(format!(
            "Provider '{}' does not support reflection",
            self.name()
        )))
    }

    /// Retrieves multiple secrets from the provider in a single batch operation.
    ///
    /// This method allows providers to optimize fetching multiple secrets at once,
    /// which can significantly improve performance for providers with high latency
    /// per request (like cloud-based secret managers).
    ///
    /// # Arguments
    ///
    /// * `project` - The project namespace for the secrets
    /// * `keys` - A slice of secret keys to retrieve
    /// * `profile` - The profile context (e.g., "default", "production")
    ///
    /// # Returns
    ///
    /// A HashMap where keys are the secret names and values are the secret values.
    /// Secrets that don't exist are not included in the result.
    ///
    /// # Default Implementation
    ///
    /// The default implementation calls `get()` for each key sequentially.
    /// Providers should override this for better performance when possible.
    fn get_batch(
        &self,
        project: &str,
        keys: &[&str],
        profile: &str,
    ) -> Result<HashMap<String, SecretString>> {
        let mut results = HashMap::new();
        for key in keys {
            if let Some(value) = self.get(project, key, profile)? {
                results.insert((*key).to_string(), value);
            }
        }
        Ok(results)
    }
}

impl<T: Provider> Provider for std::sync::Arc<T> {
    fn get(&self, project: &str, key: &str, profile: &str) -> Result<Option<SecretString>> {
        (**self).get(project, key, profile)
    }
    fn set(&self, project: &str, key: &str, value: &SecretString, profile: &str) -> Result<()> {
        (**self).set(project, key, value, profile)
    }
    fn allows_set(&self) -> bool {
        (**self).allows_set()
    }
    fn name(&self) -> &'static str {
        (**self).name()
    }
    fn uri(&self) -> String {
        (**self).uri()
    }
    fn set_reason(&self, reason: Option<String>) {
        (**self).set_reason(reason);
    }
    fn reflect(&self) -> Result<HashMap<String, crate::config::Secret>> {
        (**self).reflect()
    }
    fn get_batch(
        &self,
        project: &str,
        keys: &[&str],
        profile: &str,
    ) -> Result<HashMap<String, SecretString>> {
        (**self).get_batch(project, keys, profile)
    }
}

/// Return type from provider factories that pairs a provider with an
/// optional preflight check (e.g. authentication verification).
pub(crate) struct ProviderWithPreflight {
    pub provider: Box<dyn Provider>,
    pub preflight: Option<Box<dyn Fn() -> Result<()> + Send + Sync>>,
}

/// Wrapper that runs a preflight check exactly once before any provider
/// operation, caching the result for all subsequent calls.
struct PreflightGuard {
    inner: Box<dyn Provider>,
    preflight: Option<Box<dyn Fn() -> Result<()> + Send + Sync>>,
    result: OnceLock<std::result::Result<(), String>>,
}

impl PreflightGuard {
    fn new(pwp: ProviderWithPreflight) -> Self {
        Self {
            inner: pwp.provider,
            preflight: pwp.preflight,
            result: OnceLock::new(),
        }
    }

    fn check(&self) -> Result<()> {
        let result = self.result.get_or_init(|| {
            if let Some(f) = &self.preflight {
                f().map_err(|e| e.to_string())
            } else {
                Ok(())
            }
        });
        match result {
            Ok(()) => Ok(()),
            Err(msg) => Err(SecretSpecError::ProviderOperationFailed(msg.clone())),
        }
    }
}

impl Provider for PreflightGuard {
    fn get(&self, project: &str, key: &str, profile: &str) -> Result<Option<SecretString>> {
        self.check()?;
        self.inner.get(project, key, profile)
    }

    fn set(&self, project: &str, key: &str, value: &SecretString, profile: &str) -> Result<()> {
        self.check()?;
        self.inner.set(project, key, value, profile)
    }

    fn allows_set(&self) -> bool {
        self.inner.allows_set()
    }

    fn name(&self) -> &'static str {
        self.inner.name()
    }

    fn uri(&self) -> String {
        self.inner.uri()
    }

    fn set_reason(&self, reason: Option<String>) {
        self.inner.set_reason(reason);
    }

    fn reflect(&self) -> Result<HashMap<String, crate::config::Secret>> {
        self.check()?;
        self.inner.reflect()
    }

    fn get_batch(
        &self,
        project: &str,
        keys: &[&str],
        profile: &str,
    ) -> Result<HashMap<String, SecretString>> {
        self.check()?;
        self.inner.get_batch(project, keys, profile)
    }
}

impl TryFrom<String> for Box<dyn Provider> {
    type Error = SecretSpecError;

    /// Creates a provider instance from a URI string.
    ///
    /// This function handles various URI formats and normalizes them before parsing.
    /// It supports both full URIs and shorthand notations.
    ///
    /// # URI Formats
    ///
    /// - **Full URI**: `scheme://authority/path` (e.g., `onepassword://vault/Production`)
    ///
    /// # Special Cases
    ///
    /// - **1password**: Will error suggesting to use `onepassword` instead
    /// - **Bare provider names**: Automatically converted to `provider://`
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use std::convert::TryFrom;
    ///
    /// // Simple provider name
    /// let provider = Box::<dyn Provider>::try_from("keyring".to_string())?;
    ///
    /// // Full URI with configuration
    /// let provider = Box::<dyn Provider>::try_from("onepassword://vault/Production".to_string())?;
    ///
    /// // Dotenv with path
    /// let provider = Box::<dyn Provider>::try_from("dotenv:.env.production".to_string())?;
    /// ```
    fn try_from(s: String) -> Result<Self> {
        Self::try_from(&s as &str)
    }
}

impl TryFrom<&str> for Box<dyn Provider> {
    type Error = SecretSpecError;

    fn try_from(s: &str) -> Result<Self> {
        // Parse the scheme from the input string
        let (scheme, rest) = if let Some(pos) = s.find(':') {
            let scheme = &s[..pos];
            let rest = &s[pos + 1..];
            (scheme, rest)
        } else {
            // Just a provider name, no URI components
            (s, "")
        };

        // Validate scheme first
        if scheme == "1password" {
            return Err(SecretSpecError::ProviderOperationFailed(
                "Invalid scheme '1password'. Use 'onepassword' instead (e.g., onepassword://vault/path)".to_string()
            ));
        }

        // Check if the scheme is registered
        let is_valid_scheme = PROVIDER_REGISTRY
            .iter()
            .any(|reg| reg.schemes.contains(&scheme));

        if !is_valid_scheme {
            // Check if it's a known provider name to give a better error
            if PROVIDER_REGISTRY.iter().any(|reg| reg.info.name == scheme) {
                return Err(SecretSpecError::ProviderOperationFailed(format!(
                    "Provider '{}' exists but URI parsing failed",
                    scheme
                )));
            } else {
                return Err(SecretSpecError::ProviderNotFound(scheme.to_string()));
            }
        }

        // Build a proper URL with the correct scheme
        let url_string = match rest {
            // Just scheme name (e.g., "keyring")
            "" | ":" => format!("{}://", scheme),
            // Standard URI format already has // (e.g., "onepassword://vault/path")
            s if s.starts_with("//") => format!("{}:{}", scheme, s),
            // Path only format (e.g., "dotenv:/path/to/.env")
            s if s.starts_with('/') => format!("{}://{}", scheme, s),
            // Everything else - assume it's a host or path component
            s => format!("{}://{}", scheme, s),
        };

        // Percent-encode characters that are invalid in URIs but might appear in
        // provider config values (e.g., spaces in 1Password vault names like "Home Lab")
        let url_string = {
            let scheme_end = url_string.find("://").unwrap() + 3;
            let (prefix, rest) = url_string.split_at(scheme_end);
            format!(
                "{}{}",
                prefix,
                percent_encode(rest.as_bytes(), URI_ENCODE_SET)
            )
        };

        let proper_url = Url::parse(&url_string).map_err(|e| {
            SecretSpecError::ProviderOperationFailed(format!(
                "Invalid provider specification '{}': {}",
                s, e
            ))
        })?;

        provider_from_url(&ProviderUrl::new(proper_url))
    }
}

impl TryFrom<&Url> for Box<dyn Provider> {
    type Error = SecretSpecError;

    fn try_from(url: &Url) -> Result<Self> {
        provider_from_url(&ProviderUrl::new(url.clone()))
    }
}

fn provider_from_url(url: &ProviderUrl) -> Result<Box<dyn Provider>> {
    let scheme = url.scheme();

    // Find the provider registration for this scheme
    let registration = PROVIDER_REGISTRY
        .iter()
        .find(|reg| reg.schemes.contains(&scheme))
        .ok_or_else(|| SecretSpecError::ProviderNotFound(scheme.to_string()))?;

    let pwp = (registration.factory)(url)?;
    if pwp.preflight.is_some() {
        Ok(Box::new(PreflightGuard::new(pwp)))
    } else {
        Ok(pwp.provider)
    }
}

#[cfg(test)]
mod url_tests {
    use super::*;
    use std::collections::HashMap;
    use url::Url;

    fn url(s: &str) -> ProviderUrl {
        ProviderUrl::new(Url::parse(s).unwrap())
    }

    #[test]
    fn host_and_path_are_percent_decoded() {
        let u = url("keyring://Home%20Lab/My%20Path");
        assert_eq!(u.host().as_deref(), Some("Home Lab"));
        assert_eq!(u.path(), "/My Path");
    }

    #[test]
    fn username_and_password_are_percent_decoded() {
        let u = url("onepassword://work%40acct:tok%20en@Vault");
        assert_eq!(u.username(), "work@acct");
        assert_eq!(u.password().as_deref(), Some("tok en"));
        assert_eq!(u.host().as_deref(), Some("Vault"));
    }

    #[test]
    fn missing_password_and_port_are_none() {
        let u = url("keyring://host");
        assert_eq!(u.password(), None);
        assert_eq!(u.port(), None);
        assert_eq!(u.username(), "");
    }

    #[test]
    fn port_is_parsed_when_present() {
        assert_eq!(url("https://example.com:8200/").port(), Some(8200));
    }

    #[test]
    fn query_pairs_are_decoded() {
        let u = url("keyring://h/p?prefix=a%20b&kv=v2");
        let pairs: HashMap<String, String> = u
            .query_pairs()
            .map(|(k, v)| (k.into_owned(), v.into_owned()))
            .collect();
        assert_eq!(pairs.get("prefix").map(String::as_str), Some("a b"));
        assert_eq!(pairs.get("kv").map(String::as_str), Some("v2"));
    }

    #[test]
    fn encode_escapes_spaces_but_keeps_plain() {
        assert_eq!(ProviderUrl::encode("plain"), "plain");
        assert_eq!(ProviderUrl::encode("Home Lab"), "Home%20Lab");
    }

    #[test]
    fn provider_info_display_with_and_without_examples() {
        let with = ProviderInfo {
            name: "onepassword",
            description: "OnePassword",
            examples: &["onepassword://vault", "onepassword://work@Production"],
        };
        assert_eq!(
            with.display_with_examples(),
            "onepassword: OnePassword (e.g., onepassword://vault, onepassword://work@Production)"
        );

        let without = ProviderInfo {
            name: "env",
            description: "Environment variables",
            examples: &[],
        };
        assert_eq!(
            without.display_with_examples(),
            "env: Environment variables"
        );
    }
}