Comparison

SecretSpec is the application-facing layer of a secrets system. It defines what an application needs, resolves those requirements across environments, and delivers the resulting values through its CLI and provider-independent SDKs. Providers connect that layer to concrete value sources. Depending on the backend, they can add secure storage, identity, access control, availability, and provider-native operations.

This separation keeps secretspec.toml portable. A developer can use the system keyring, CI can supply environment variables, and production can use Vault or a cloud secret manager without changing the application’s secret contract.

secretspec.toml          SecretSpec                         Provider
what the app needs  →    resolve · check · deliver    ←    provider-backed values
                         route · audit                      source · access

Division of responsibility

Responsibility	SecretSpec	Providers augment SecretSpec with
Application secret contract	Declares names, descriptions, requirements and defaults, generated values, and composed values	Supply provider-backed values named by that contract
Environments	Defines portable profiles, configuration inheritance, and profile-specific requirements	Add provider-native projects, vaults, paths, or environments
Preflight validation	check validates required secrets and configuration before the application starts	Report whether a requested value exists or can be accessed
Provider selection	Routes each secret independently through provider aliases and ordered fallback chains	Supply concrete sources and destinations
Existing provider-native secrets	Uses secret references to give an existing value a stable, application-facing name	Interpret provider-specific coordinates such as vault, item, field, path, or version
Application delivery	Resolves secrets through the CLI, exports environments, starts child processes, and manages temporary files	Supply values through provider APIs or clients
Application SDKs	Offers one provider-independent resolver with a shared runtime API and typed access across supported programming languages	Vendor SDKs, when available, remain backend-specific; applications do not need to integrate them directly
Audit	Records local, metadata-only access events by default, including application context and optional reason	Add centralized, provider-side access records where supported and configured
Encryption at rest	Delegates protection of provider-backed values to the selected provider	Protect values when the backend supports encryption; dotenv and environment providers add no at-rest encryption
Identity and access policy	Uses the credentials available for the selected provider, including credentials sourced from another provider	Enforce users, roles, service identities, policies, and sharing
Availability and retention	Delegates these guarantees for provider-backed values	May provide synchronization, replication, versions, backup, or retention, depending on the provider
Dynamic secrets and credential rotation	Roadmap; not currently available and has no assigned target release	Provide native lifecycle features where available; use them outside SecretSpec today

The distinction is intentional: SecretSpec provides portable application semantics, while each provider determines how its provider-backed values are stored, protected, and operated. Some providers, such as dotenv and environment variables, intentionally provide fewer safeguards. SecretSpec’s default audit log complements provider logs by recording the project, profile, secret name, outcome, actor, and reason seen by the application workflow. It is a size-bounded, best-effort local log, not a replacement for central compliance records.

Supported providers

See Available providers for the provider comparison, including storage backend, read and write support, encryption at rest, and TPM-backed keys.

Providers can be mixed within one project. For example, an application can read a shared credential from 1Password in the production profile, read the same secret from the system keyring in the development profile, and accept a deployment token from the environment in CI. A secret can also define an ordered fallback chain, which tries the next provider when an earlier provider does not return the value. SecretSpec keeps those storage decisions outside the application’s code.