Crate secretspec 

SecretSpec - A declarative secrets manager for development workflows

This library provides a type-safe, declarative way to manage secrets and environment variables across different environments and storage backends.

Features

• Declarative Configuration: Define secrets in secretspec.toml
• Rust-first Declarations: Build a Spec directly in Rust (0.20+)
• Multiple Providers: Keyring, dotenv, environment variables, Keeper Secrets Manager (0.18+)
• Profile Support: Different configurations for development, staging, production
• Type Safety: Optional compile-time code generation for strongly-typed access
• Validation: Ensure all required secrets are present before running applications

Example

// Generate typed structs from secretspec.toml
secretspec_derive::declare_secrets!("secretspec.toml");

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load secrets and configure provider/profile
    let mut spec = Secrets::load()?;
    spec.set_provider("keyring");  // Can use provider name or URI like "dotenv:/path/to/.env"
    spec.set_profile("development");
     
    // Validate and get secrets
    let secrets = match spec.validate()? {
        Ok(validated) => validated,
        Err(errors) => return Err(format!("Missing secrets: {}", errors).into()),
    };

    // Access secrets (field names are lowercased)
    println!("Database: {}", secrets.resolved.secrets.get("DATABASE_URL").unwrap());

    // Access profile and provider information
    println!("Using profile: {}", secrets.resolved.profile);
    println!("Using provider: {}", secrets.resolved.provider);

    Ok(())
}

Modules

cli

Structs

CallerContext

Describes the software integration that requested secret access.

ConstraintViolation

A failed cross-secret presence constraint.

CredentialSource

Where one credential required by a provider comes from.

DiscoveryContext

Context supplied when a provider discovers secret declarations.

NativeAddress

Native coordinates of one externally managed secret: the value of a secret’s ref field.

NativeAddressTemplate

A provider-alias template for native secret coordinates (0.19+).

Profile

One profile in a Rust-built Spec.

ProviderAlias

A provider alias: either a leaf provider or, in SecretSpec 0.17+, a cached fallback route.

ProviderCache

Cache policy for a cached provider alias. Available since SecretSpec 0.17.

ResolutionReport

A complete, value-free snapshot of one resolution pass over a profile.

ResolveResponse

A complete value-carrying resolution result for one profile.

Resolved

Container for resolved secrets with their context.

ResolvedSecret

One resolved secret. Exactly one of value or path is set: path when the secret is materialized to a temp file (as_path), value otherwise.

Secret

One secret declaration in a Rust-built Spec.

SecretExtract

Selects one logical secret from a structured stored value.

SecretResolution

The resolution outcome for one declared secret. Never carries the value.

Secrets

The main entry point for the secretspec library

Spec

A validated, format-independent description of a SecretSpec project.

SpecBuilder

Rust-first construction of a Spec.

ValidatedSecrets

Container for validated secrets with metadata

ValidationErrors

Container for validation errors

Enums

ConstraintKind

The kind of cross-secret presence constraint that failed.

ExportFormat

Output format for Secrets::export

ExtractFormat

A structured-data format from which one logical secret can be extracted.

Generation

A typed secret-generation strategy.

NamedResolution

The outcome of resolving one secret by name with crate::Secrets::resolve_named.

PasswordCharset

Character set used by Generation::Password.

ProducedValuePersistence

Whether a value SecretSpec produces after a provider miss is written back to the primary provider.

RequireReason

When secretspec requires a reason for secret access.

ResolutionStatus

How a single declared secret resolved.

ResolvedSource

Where a resolved value came from.

SecretEncoding

Text encoding used for a secret’s stored representation.

SecretSpecError

The main error type for secretspec operations

Constants

INLINE_SPEC_SCHEMA_VERSION

The version of the JSON inline-declaration document understood by this library.

NATIVE_CALL_REQUEST_VERSION

The version of the native call envelope understood by this library.

RESOLUTION_REPORT_SCHEMA_VERSION

Version of the ResolutionReport wire format.

RESOLVE_SCHEMA_VERSION

Version of the ResolveResponse wire format.

Traits

Provider

Trait defining the interface for secret storage providers.

Functions

call_json

Process a versioned native request and return its JSON response envelope.

resolve_json

Resolve secrets from a JSON request string and return the JSON response envelope: {"ok": true, "response": <ResolveResponse | ResolutionReport>} or {"ok": false, "error": {"kind", "message"}}.

Type Aliases

Result

A type alias for Result<T, SecretSpecError>