Secret lifetimes

[domenkozar]

Ideally, secrets live for a certain amount of time, then it's time to request a new secret.

There are two aspects where this becomes tricky:

• keep the state of how long the secret is still valid for
• provide an api when to reload the app after a new secret is fetched

The API would look something like:

let secrets = SecretSpec::builder().load()?;

for secret in secrets.next() {
   ...
}

for mysecret in secrets.mysecret.next() {
   ...
}

[aggaksha]

It depends on how secrets are being loaded when needed. If the env file captures a secret reference/ name (such as Secret ARN from AWS Secrets Manager), the env file is evaluated to the run time, and secret value are fetched at that time, you will have the latest value of secret. Of course, once evaluated to secret value, it can not be updated without re-starting the application.
With secret rotation being an async process on AWS Secrets Manager, we have solved this problem through our open source clients such as Secrets Manager Agent and CSI Driver. Happy to engage with the team and help solve this industry-wide challenge.

[domenkozar]

This will come after #9

[blaggacao]

provide an api when to reload the app after a new secret is fetched

Or send a process signal, which may be understood by the app as instructions to just reload the credential context, instead the entire app.

[blaggacao]

keep the state of how long the secret is still valid for

Or fetch validity information from a revocation mechanism - this may be an advanced use case and not necessary for many scenarios, but it is critical enough in others that it might be worth considering plugging into some sort of established standard.

[domenkozar]

Pulling threads from the discussion together. I think this naturally splits into three shippable slices:

1. Provider TTL tracking. Extend the Provider trait with something like:

fn get_with_lease(&self, key: &str) -> Result<(String, Option<Lease>)>;

Static providers (keyring, dotenv, 1Password) return None. Lease-capable providers (Vault dynamic secrets, AWS STS, GCP IAM tokens) return a real expiry plus optional renew handle. Everything else builds on this.

2. SDK refresh API. Once lease info exists, the SDK exposes a stream of updates. The iterator shape from the issue body works, though I'd lean async so apps only re-wire the specific key that rotated:

let mut secrets = SecretSpec::builder().load().await?;

while let Some(update) = secrets.next_refresh().await {
    reload_db_pool(&update.database_url);
}

Static secrets simply never emit, so the same code is safe for any provider mix.

3. Reload contract for secretspec run. For wrapped commands the CLI owns the signal. SIGHUP on rotation (per @blaggacao) is the right default since it matches the nginx / postgres / haproxy convention. An opt-in --reload-signal SIGUSR1 flag covers apps that bind HUP elsewhere. Re-exec of the child works as a fallback for apps that can't handle signals at all, behind a flag.

Prior art worth borrowing from:

• Vault Agent: clean split between fetch lifecycle and app signaling, maps almost 1:1 to (1)+(2) vs (3).
• AWS Secrets Manager Agent: sidecar caching with refresh, similar contract.

@aggaksha the most useful AWS-side contribution would be sketching how Secrets Manager Agent's refresh semantics map onto the `Provider::get_with_lease` shape above, since that trait is what the rest of the design hangs off.

@blaggacao revocation is a real concern but I'd push it to v2. Most lease backends publish TTL on issue, so we know when to refresh without polling a revocation endpoint. Revocation lists are an optimization for "this secret was just compromised, drop it now," which is a different problem worth its own issue.

Still gated on #9, but happy to keep the design moving in parallel.