Crate secretspec

Expand description

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.
ExternalProvider: A core provider backed by one secretspec.provider/1 endpoint.
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+).
PlatformEndpointSecurity
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.
ProviderCredentialPrincipal: The host-selected provider instance a credential request belongs to (0.21+).
ProviderCredentialRequest: Semantic credential request made by an external endpoint (0.21+). One semantic provider credential requested while an endpoint is initializing or refreshing its authentication (0.21+).
ProviderDiscovery: Explicit inputs to external-provider discovery.
ProviderEndpoint: A resolved provider endpoint and its fixed executable identity.
ProviderInfo: Information about a secret storage provider.
ProviderValue: A provider value with optional authoritative validity and revision metadata.
ResolutionReport: A complete, value-free snapshot of one resolution pass over a profile.
ResolveResponse: A complete value-carrying resolution result for one profile. The default String payload is the JSON wire format; Rust byte resolution uses ResolveResponse<SecretBytes> (0.21+) without a Serde representation.
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. The default inline type is String for text/JSON APIs. Byte resolution APIs use crate::SecretBytes starting with 0.21.
Revision: A provider-defined identity and generation token, or a resolver-derived token for the logical value. Equality is meaningful; ordering is not.
Secret: One secret declaration in a Rust-built Spec.
SecretBytes: An owned, zeroizing secret byte sequence.
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§

Address: How a provider operation addresses a secret.
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.
OpenPgpAlgorithm: The cryptographic profile for a generated OpenPGP key.
OpenPgpCapability: A capability assigned to a generated OpenPGP subkey.
PasswordCharset: Character set used by Generation::Password.
ProducedValuePersistence: Whether a value SecretSpec produces after a provider miss is written back to the primary provider.
RegistrationScope: Scope used by the injectable endpoint security policy.
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
SshKeyAlgorithm: The algorithm for a generated OpenSSH private key.

Constants§

BASE_ENDPOINT_ENVIRONMENT: Parent environment variables every endpoint receives: what a process needs to find programs, locale, temporary and user directories, proxies, certificate stores, and desktop or agent sessions for native authentication. Anything else, including other providers’ tokens, reaches an endpoint only when its registration names it. Entries ending in * are prefixes.
INLINE_SPEC_SCHEMA_VERSION: The version of the JSON inline-declaration document understood by this library.
MIN_INLINE_SPEC_SCHEMA_VERSION: The oldest inline-declaration document version this library still accepts.
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§

EndpointSecurity: Platform security seam used by discovery tests and embedders with a stronger host-specific ACL policy.
Provider: Trait defining the interface for secret storage providers.
ProviderCredentialBroker: Resolves credentials requested by one already-discovered external provider.

Functions§

call_json: Process a versioned native request and return its JSON response envelope.
providers: Returns metadata for all built-in providers.
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"}}.
set_provider_discovery: Replaces the process-wide discovery inputs used by ordinary provider URI construction. Embedders can use this to supply trusted direct endpoints or to opt into PATH discovery. Available since SecretSpec 0.21.

Type Aliases§

Result: A type alias for Result<T, SecretSpecError>

Crate secretspec

Crate secretspec Copy item path

§Features

§Example

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate secretspec