backfill_from: migrates a plaintext column. When the column is already stored by
another Ash type — an app-level encrypted type under a global key, typically — the
attribute usually has readers and an API contract that must not move while the copy is
being built. legacy: is the expand step for that case.
attributes do
# Declared with the type of the AshVault copy.
attribute :api_key, :binary, public?: true, sensitive?: true
end
ash_vault do
vault MyApp.Vault
scope :tenant
encrypt :api_key,
legacy: MyApp.Encrypted.Binary,
encrypt_nil?: false,
decrypt_for: [MyApp.Checks.IsSystemActor, {MyApp.Checks.Gateway, only: [:read]}]
endWhat it generates
api_key | the original attribute and column, retyped to MyApp.Encrypted.Binary — every reader, filter and JSON:API schema stays as it was |
encrypted_vault_api_key | the AshVault ciphertext (stored_as: overrides vault_api_key; the AEAD binding uses the same name) |
vault_api_key | the private decrypt calculation, of the declared type |
| a global change | on every create and update: when the action changes api_key, the value is also encrypted into the copy |
| a global preparation | for decrypt_for actors, api_key reads the decrypted copy when a row has one |
There is nothing to opt into per action. Accepted input, set_attribute/2, a custom
change and a value forced in an earlier before_action hook are all mirrored; an action
that leaves the attribute alone keeps its ciphertext and stays atomic. An upsert whose
upsert_fields lists api_key gets encrypted_vault_api_key added. The verifier
rejects the two shapes the dual-write cannot follow: atomic_update/2 on the attribute,
and an upsert that keeps the ciphertext on conflict.
Values
The copy holds the value as the legacy type reads it back: it is dumped and cast
through the legacy type first. A JSON-backed map therefore stores string keys in both
copies, and mix ash_vault.verify compares like with like.
Reads
decrypt_foractors read the AshVault copy. A row without one yet reads the legacy value. A decrypt error —KeyDestroyed,ProviderUnavailable,ProviderForbidden, integrity — fails the read; it is never answered from the legacy column.- Everyone else reads the legacy value, subject to your field policies.
- An entry
{check, only: [actions]}matches only on those read actions, so a broadly read resource can decrypt for its system actor on one dedicated action only. - A native sibling read preserves the action, arguments, actor, tenant, public context, filter and lock, bounded to the selected rows' primary keys. Preparations and field authorization run again; existing hooks and private state are not reused. Missing, duplicate or changed rows fail closed. Pagination is not applied a second time. Keep preparations safe to repeat: the dual-read preparation suppresses only its own nested read, once per selected field and tenant chunk.
- Caller-supplied record loads retain
query_for: :load. They cannot gain fresh-read authority through the internal read or by setting its public recursion marker. - Skipped: actor-less reads (so verify compares the real legacy column), the row query of a bulk update or destroy, and queries that do not select the attribute.
Without decrypt_for nothing is swapped: the copy is written and backfilled, but reads
keep the legacy value.
Backfill and verify
The copy is an ordinary encrypted field named stored_as, backfilled from the legacy
attribute:
mix ash_vault.backfill --resource MyApp.Account --field vault_api_key --tenant acme
mix ash_vault.verify --resource MyApp.Account --field vault_api_key --tenant acme
Rollback
The legacy column is kept current by every write, so an older release keeps working.
It does not write the copy, though: before rolling forward again, set the ciphertext
column to NULL and backfill, or the copy may be older than the legacy value.
Contract
Once every row verifies, replace the declaration with ordinary encryption and preserve its storage/binding name explicitly:
encrypt :api_key, stored_as: :vault_api_keyThe native public calculation and write argument remain api_key; ciphertext stays in
encrypted_vault_api_key under the same resource/scope/vault_api_key AAD. No sibling,
dual-write change or preference preparation is generated. Remove the old encrypted type
and legacy attribute column after verifying the deployed readers and writers use this
single native path. Never change the resource module or stored binding identity without
an explicit ciphertext migration.
The direct calculation has no trusted action name: an action-only decrypt_for entry
remains denied. Preserve authorization with native resource/field policies and normalized
actor/scope checks, or address action lifecycle context separately. Caller-supplied
source context is not authority.