Audit Secret Caching and Stale Fallbacks in Hermes

External secret managers add a network and subprocess dependency to startup. Caching can reduce repeated vault calls and help short-lived commands, but it must not turn an authentication failure into apparently healthy use of a revoked credential. Review cache behavior as part of the security policy, not as an invisible performance detail.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/secrets/bitwarden

Distinguish fresh reuse from stale recovery

A normal TTL reuses a recent successful fetch. A stale fallback is different: it may be considered only after specific network or timeout failures and only within a configured age. Authentication failures should not use stale material because a revoked token is an explicit trust decision, not a connectivity problem. Partial or errored pulls should not become the new complete cache.

1Password can disable both cache layers with a zero TTL. Bitwarden can use an encrypted cache with a separate maximum stale age. Whichever source you operate, understand what is stored, how cache keys change with identity or references, and which file permissions protect the cache.

Cache-policy checklist

Decide whether the installation needs disk caching at all.
Set a TTL proportional to command frequency and rotation expectations.
Encrypt stale caches when the backend supports it.
Keep maximum stale age finite and documented.
Never allow authentication failure to trigger stale recovery.
Reject empty and partial fetches as cache replacements.
Verify cache files are atomic and owner-readable only.
Include cache cleanup in decommission and incident runbooks.

Common pitfalls

Using a long TTL that delays urgent key rotation.
Calling any cached value “fresh” without checking age and fetch result.
Falling back after revocation or invalid-client errors.
Leaving a legacy plaintext cache after enabling encrypted storage.
Sharing one cache across accounts without identity-sensitive keys.
Debugging by opening a cache file and exposing secret values.

Verification steps

Populate the cache through one complete successful fetch.
Repeat within the TTL and confirm the expected reuse path.
Change the reference set or authentication identity and confirm invalidation.
Simulate a network timeout and verify stale use occurs only when explicitly allowed.
Simulate an authentication rejection and confirm stale data is refused.
Simulate a partial fetch and verify it is not persisted as healthy state.
Inspect file mode, encryption setting, age limits, and cleanup behavior without reading values into logs.