Trait Provider 

pub trait Provider: Send + Sync {
    // Required methods
    fn get(
        &self,
        project: &str,
        key: &str,
        profile: &str,
    ) -> Result<Option<SecretString>>;
    fn set(
        &self,
        project: &str,
        key: &str,
        value: &SecretString,
        profile: &str,
    ) -> Result<()>;
    fn name(&self) -> &'static str;
    fn uri(&self) -> String;

    // Provided methods
    fn allows_set(&self) -> bool { ... }
    fn set_reason(&self, _reason: Option<String>) { ... }
    fn with_base_dir(&mut self, _base_dir: &Path) { ... }
    fn reflect(&self) -> Result<HashMap<String, Secret>> { ... }
    fn get_batch(
        &self,
        project: &str,
        keys: &[&str],
        profile: &str,
    ) -> Result<HashMap<String, SecretString>> { ... }
}

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 names should be lowercase and descriptive

Required Methods

fn get( &self, project: &str, key: &str, profile: &str, ) -> Result<Option<SecretString>>

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

match provider.get("myapp", "DATABASE_URL", "production")? {
    Some(url) => println!("Database URL: {}", url),
    None => println!("DATABASE_URL not found"),
}

fn set( &self, project: &str, key: &str, value: &SecretString, profile: &str, ) -> Result<()>

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 returns false.

Example

provider.set("myapp", "API_KEY", "secret123", "production")?;

fn name(&self) -> &'static str

Returns the name of this provider.

This should match the name registered with the provider macro.

fn uri(&self) -> String

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.

Provided Methods

fn allows_set(&self) -> bool

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 operations
• false if the provider is read-only

Example

if provider.allows_set() {
    provider.set("myapp", "TOKEN", "value", "default")?;
} else {
    eprintln!("Provider is read-only");
}

fn set_reason(&self, _reason: Option<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).

fn with_base_dir(&mut self, _base_dir: &Path)

Rebases any relative filesystem paths the provider holds against base_dir, the directory containing the secretspec.toml that configured it.

File-backed providers (e.g. dotenv) take paths from the config or its provider aliases. Those paths must resolve relative to the project root, not the process’s current working directory — otherwise running from a subdirectory with --file ../secretspec.toml looks for the .env file in the wrong place. Secrets calls this once at construction, before the provider performs any I/O. The default implementation does nothing, which is correct for providers that hold no relative paths.

fn reflect(&self) -> Result<HashMap<String, Secret>>

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

let secrets = provider.reflect()?;
for (name, secret) in secrets {
    println!("Found secret: {} = {:?}", name, secret);
}

fn get_batch( &self, project: &str, keys: &[&str], profile: &str, ) -> Result<HashMap<String, SecretString>>

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.

Trait Implementations

impl TryFrom<&Url> for Box<dyn Provider>

type Error = SecretSpecError

The type returned in the event of a conversion error.

fn try_from(url: &Url) -> Result<Self>

Performs the conversion.

impl TryFrom<&str> for Box<dyn Provider>

type Error = SecretSpecError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Self>

Performs the conversion.

impl TryFrom<String> for Box<dyn Provider>

fn try_from(s: String) -> Result<Self>

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

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())?;

type Error = SecretSpecError

The type returned in the event of a conversion error.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<T: Provider> Provider for Arc<T>

fn get( &self, project: &str, key: &str, profile: &str, ) -> Result<Option<SecretString>>

fn set( &self, project: &str, key: &str, value: &SecretString, profile: &str, ) -> Result<()>

fn allows_set(&self) -> bool

fn name(&self) -> &'static str

fn uri(&self) -> String

fn set_reason(&self, reason: Option<String>)

fn reflect(&self) -> Result<HashMap<String, Secret>>

fn get_batch( &self, project: &str, keys: &[&str], profile: &str, ) -> Result<HashMap<String, SecretString>>

Implementors