Module secrets 

Secret source extension point.

Contract: SecretSource

Purpose: resolve named secrets (TLS key passphrases, upstream credentials, plugin tokens) at runtime without baking values into configuration.

Semantics: resolve is a single lookup, None meaning “this source does not know this secret” (callers may chain sources). Resolution is not on the request hot path for M1; implementations must never log the resolved value.

Failure model: a source that knows where the secret lives but cannot read it (backend sealed, file unreadable) returns ExtensionsError::Io or ExtensionsError::Backend — distinguishable from a plain miss (Ok(None)). No retries.

Editions: OSS ships EnvSecretSource (environment variables), FileSecretSource (secret files by path, DW-045), and StaticSecretSource (in-process map, for tests). Additional managed secret-store backends may be provided separately in future editions.

Config integration (DW-045)

The ${...} secret-reference grammar that secret-bearing config fields (api_key.key) accept is defined in config::credentials and resolves through the same env/file reading rules these local impls use, so the config grammar cannot drift from the extension seam. References are resolved at CONFIG-COMPILE time (cold start and every reload), never per request; see that module’s docs for the read-time model and the fail-closed validation contract. FileSecretSource re-reads the file on every resolve call (no caching): resolution happens at publish cadence, so a rotation lands on the next reload for the cost of one small read per publish.

Secret handling

Secret wraps the value as a newtype over String. Its Debug impl is redacted so values cannot leak into logs. Zeroization on drop is a future hardening step; adopting the secrecy crate then would change the wrapper’s internals, not the trait.

Structs

EnvSecretSource

Environment-variable secret source (OSS): name maps to the identical environment variable name. An unset variable is a miss (Ok(None)); a variable that is set but not valid Unicode is reported as ExtensionsError::Invalid (present but unreadable), never a silent miss.

FileSecretSource

File secret source (OSS, DW-045): name IS the file path. The file is read on EVERY resolve call (no caching — a rotation lands on the next resolve) with the same rules the config grammar applies (see read_secret_file): one trailing newline trimmed, non-empty remainder, UTF-8.

Secret

A resolved secret value.

StaticSecretSource

Static in-process map of secrets, primarily for tests and examples.

Traits

SecretSource

Swappable secret resolution backend.