A rotation policy answers one question, per scope, per operation: should this write mint a new key version first? It never decides anything about reads — a value is always decrypted with the key version its envelope names.
The default, AshVault.RotationPolicies.Manual, answers "no" forever. Keys rotate only
when something explicitly asks: mix ash_vault.rotate, AshVault.rotate_key!/2, or a
key_lifecycle generic action.
The contract
@callback policy(scope :: term(), AshVault.Context.t()) :: AshVault.RotationPolicy.t()It returns a struct, not a decision:
%AshVault.RotationPolicy{
strategy: :manual | :age | :provider,
max_age: Duration.t() | nil,
rotate_on_write?: boolean()
}AshVault.RotationPolicy.due?/3 interprets it:
:manualand:provider→ never due. Rotation is driven from outside.:agewith amax_age→ due oncekey_info.created_atis older thannow - max_age, viaDateTime.shift/2andDateTime.compare/2.
And AshVault.Vault.Runtime acts on it only when both hold:
if policy.rotate_on_write? and RotationPolicy.due?(policy, key_info) doSo rotate_on_write? is the master switch and strategy is the schedule. A policy with
strategy: :age but rotate_on_write?: false is a description of when you intend to
rotate that nothing acts on automatically — which is a perfectly reasonable thing to
return if a scheduled job reads it and calls AshVault.rotate_key!/2 itself.
:provider exists for key stores with their own rotation schedule (a KMS rotating on its
own clock). AshVault does not rotate those; it just keeps reading whatever
current_key/1 returns.
Failure modes that matter
Rotation must never fail a write
This is the load-bearing rule. AshVault.Vault.Runtime logs a warning and continues with
the existing key when rotate/1 fails:
AshVault: key rotation for scope "acme" failed (:timeout); continuing with the existing
key for MyApp.Accounts.User.emailA key that is a day past its rotation date is a hygiene problem. A write that 500s because the key store was briefly slow is an outage. Do not build a policy that assumes rotation will succeed.
…except when the scope is destroyed
There is exactly one failure that is not best-effort. If rotate/1 answers
{:error, :destroyed}, a write is racing a destroy! and the pre-destroy key is about to
become unusable. Falling back to it would produce a write that "succeeds" while storing
ciphertext nobody can ever read. The runtime raises AshVault.Errors.KeyDestroyed
instead. You get this for free — just do not reimplement rotation in your own policy
module and lose it.
policy/2 runs on every single write
It is on the hot path. Return a module attribute; do not hit the network, the database, or
a GenServer you might block on. If the policy needs external state, cache it (an ETS
table refreshed by a periodic task) and read the cache here.
:age needs a truthful created_at
An :age policy is only as good as the provider's timestamps. A provider that fabricates
created_at: DateTime.utc_now() when its metadata is unavailable produces a key that is
never older than any max_age, so the policy silently never fires and nothing logs a
reason. That is why the provider contract suite asserts created_at is stable across
calls — see Writing a key provider.
Rotation is not re-encryption
A policy that rotates hourly does not make yesterday's rows any more protected: they still
carry key_version: n and still decrypt. Frequent rotation buys you a smaller blast
radius for future writes and a shorter window for a leaked key — nothing more, unless
you also re-encrypt. See Rotation.
Rotating per write is not a security upgrade
max_age: Duration.new!(second: 0) with rotate_on_write?: true mints a key version on
every write. Some providers charge per version, some list them all in metadata, and
mix ash_vault.key_info will print thousands of them. Every version has to be retained
forever for old rows to decrypt, so this is a monotonically growing liability. Do not do
it outside tests (where AshVault.Test.Support.RotateOnWritePolicy does exactly this, on
purpose, to make the rotation path deterministic).
A worked example
Rotate at most once every 30 days, opportunistically on write, and never for scopes that are still in a trial:
defmodule MyApp.RotationPolicy do
@moduledoc """
Rotate a scope's key when it is older than 30 days, opportunistically on the next
write. Trial scopes are left on `:manual` — they are short-lived, and a trial that
never converts is erased wholesale rather than rotated.
Rotation here is best-effort by construction: `AshVault.Vault.Runtime` logs and
continues with the existing key if the provider cannot rotate, so a slow key store
never fails a customer write.
"""
@behaviour AshVault.RotationPolicy
alias AshVault.RotationPolicy
@monthly %RotationPolicy{
strategy: :age,
max_age: Duration.new!(day: 30),
rotate_on_write?: true
}
@manual %RotationPolicy{strategy: :manual}
@impl AshVault.RotationPolicy
@spec policy(term(), AshVault.Context.t()) :: RotationPolicy.t()
def policy(scope, _context) do
# Read-only, in-memory lookup. `policy/2` is on every write's hot path.
if MyApp.Tenants.trial?(scope), do: @manual, else: @monthly
end
endTwo things worth noting about the signature. The scope is the resolved binary scope key,
so this is where per-tenant policy belongs. The AshVault.Context.t() gives you the
resource and field as well, if you want a shorter rotation period for one sensitive
column than for the rest — though remember every version you mint has to be retained
forever.
Wiring it up
defmodule MyApp.Vault do
use AshVault.Vault,
key_provider: MyApp.KeyProviders.Sql,
rotation_policy: MyApp.RotationPolicy
endThere is no resource-level rotation setting; the policy belongs to the vault, next to the provider whose keys it rotates.
The alternative: don't
For most applications the honest answer is a scheduled job and the default :manual
policy:
# once a quarter, per tenant
mix ash_vault.rotate MyApp.Accounts.Organization --all-tenants MyApp.Accounts.list_tenant_ids/0 --yesThis is easier to reason about, easier to audit, visible in your deploy logs, and does not put a policy decision on the write path. Write a rotation policy when you need rotation to be a property of the data rather than of your crontab.
Testing it
test/ash_vault/rotation_policy_test.exs is the model. Assert:
due?/3for the boundary cases — exactly atmax_age, one second either side — by passing an explicitnow, neverDateTime.utc_now();:manualand:providerare never due, whatever thecreated_at;- a
nilcreated_atis not due (it falls through to the catch-all clause rather than raising); - end to end: encrypt, assert the stored envelope's
key_versionwithAshVault.Envelope.decode/1— do not infer it — then encrypt again and assert the version moved (or did not); - a provider whose
rotate/1fails does not fail the write. UseAshVault.Test.Support.FailingRotateProvider.