init() — resolve once, at boot
sec:// value in process.env is replaced with its real value, once.
After that your process holds plain strings in memory.
A rotation reaches this process on its next restart, and not before.
Right for: short-lived processes, CLI tools, anything that already reads config
once at startup.
expandString() — resolve at the moment of use
cacheTtlMs defaults to 0). A long-running process
picks up a rotation without a restart:
The tradeoff, stated plainly
Use-time resolution couples every use to your vault being reachable and your credentials being valid right now. Load-time resolution reads once and then survives anything — vault down, network gone, credentials expired. That is a real availability cost, and it is the honest price of the rotation guarantee.Concurrent resolutions of the same reference are coalesced into a single
fetch, so use-time resolution costs one round trip per distinct reference in
flight — not one per call site.
Tuning it
cacheTtlMs trades a bounded window of staleness for fewer round trips.
staleGraceMs is narrower and worth understanding before you enable it: after a
failed refresh, a value fetched within the window may be served instead of
throwing. It applies only to transient faults — network, timeout, throttle,
5xx.