AshVault is five layers. Each one has a behaviour, a default implementation, and exactly one job.
Ash resource
└─ AshVault (Spark extension) transformers rewrite the resource
├─ AshVault.Changes.Encrypt write path (before_action / atomic)
└─ AshVault.Calculations.Decrypt read path (calculation)
│
▼
AshVault.Vault bundles the five components below
├─ AshVault.Scope operation → scope key (a binary)
├─ AshVault.KeyProvider scope → key material, rotation, erasure
├─ AshVault.Cipher (plaintext, key, aad) → (ciphertext, nonce, tag)
├─ AshVault.Envelope payload → the bytes stored in the column
└─ AshVault.RotationPolicy should this write rotate first?Everything below AshVault.Vault is plain Elixir with no Ash dependency at runtime. You
can use a vault directly — MyApp.Vault.encrypt!/2 — without Ash in the picture at all.
The extension layer
use Ash.Resource, extensions: [AshVault] plus an ash_vault section replaces every
encrypted attribute at compile time. For encrypt :email,
AshVault.Transformers.SetupEncryption:
- removes the
:emailattribute entity from the resource, - adds an
encrypted_email:binaryattribute —sensitive?: true,public?: false,allow_nil?: true, - adds an
:emailcalculation of the original type, runningAshVault.Calculations.Decrypt,filterable?: false, sortable?: false, - rewrites every
:create/:update/:destroyaction that accepted:emailso it takes an:emailargument of the original type (sensitive?: true) plus anAshVault.Changes.Encryptchange, and drops:emailfromaccept.
Removing the attribute entity is the non-persistence mechanism. There is no plaintext
column, so no data layer can write one — this does not rely on private?, on scrubbing,
or on anyone remembering to omit a field.
The backing column is always nullable
The encrypted_<field> attribute is allow_nil?: true regardless of the original
attribute's nullability. With encrypt_nil?: false a nil value legitimately stores SQL
NULL, and an allow_nil?: false column would reject it. Real nullability is enforced by
the calculation's allow_nil? and the action argument's allow_nil? instead.
Write path
AshVault.Changes.Encrypt runs in a before_action hook, not at change/3 time, and
reads the argument (there is no attribute to read). If the argument is absent the
changeset is untouched, so a partial update never clobbers existing ciphertext.
AshVault.encrypt_and_set/4 then force-changes the backing attribute and scrubs the
plaintext out of changeset.arguments and changeset.params — without that, plaintext
survives in inspect output, telemetry and error reports long after encryption.
atomic/3 is implemented too, returning the three-element
{:atomic, changeset, %{encrypted_email => blob}} form so the scrubbed changeset comes
back as well. Both paths scrub.
Crypto failures are converted to Ash.Changeset.add_error/2, so MissingScope,
KeyDestroyed and ProviderUnavailable surface as ordinary Ash errors rather than a
raise from inside a hook.
Read path
The load/3 callback of AshVault.Calculations.Decrypt returns [:encrypted_email],
and that single line is the whole dependency declaration. Ash selects the backing attribute even though it is
public?: false, records it in query.context[:private][:depended_on_fields], and strips
it from the returned record — ciphertext does not leak into results nobody asked for.
The calculation returns {:error, %AshVault.Errors.KeyDestroyed{}} rather than raising, so
a crypto-erased tenant comes out of Ash.read/2 as a clean error and not a 500. It never
returns :unknown, which to Ash means "fall back to the data layer" — for an encrypted
field that would silently yield ciphertext or nil.
A field policy denying the field makes the backing value %Ash.ForbiddenField{}, which is
passed through untouched. AshVault performs no authorization of its own: if a read reached
the calculation, Ash already authorized it.
The plaintext format (AVP)
Before anything is encrypted, the value is serialized by AshVault.Serializer:
<<"AVP", 1::8, :erlang.term_to_binary(dumped)::binary>>dumped is always Ash.Type.dump_to_embedded/3 of the value — for scalars, arrays,
arrays of embedded resources, embedded resources and unions alike. One code path, one
on-disk shape. Type and constraints are read from
Ash.Resource.Info.calculation(resource, field), not attribute/2, because the
attribute no longer exists after the transformer runs.
Decoding is paranoid on purpose: the magic and version must match, a compressed external
term (<<131, 80, ...>>) is refused outright (:safe does not stop a decompression bomb),
and decoding goes through Ash's non_executable_binary_to_term/2 helper with :safe,
which blocks atom interning and funs/refs/ports.
The envelope, and why it carries the key version
AshVault.Envelope.V1 is the wire format written to the column:
<<"AV", # magic
1 :: 8, # envelope version
cid_len :: 8,
cipher_id :: binary-size(cid_len), # e.g. "aes_256_gcm_v1"
key_version:: 32-unsigned-big,
nonce_len :: 8,
nonce :: binary-size(nonce_len),
tag_len :: 8,
tag :: binary-size(tag_len),
ciphertext :: binary>>Three fields in that header each buy something specific:
- cipher id — decryption looks the cipher back up through
AshVault.Cipher.fetch/1, so a value is always decrypted with the cipher that wrote it, even after the vault's default cipher changes. The registry is keyed by the binary id, exactly what the envelope stores, so the encode and decode directions cannot drift. - envelope version —
AshVault.Envelope.decode/1peeks the version byte and dispatches, so values written by older builds keep decoding. - key version — this is what makes rotation without re-encryption possible. Rotating a scope's key mints version n+1 and leaves every existing row alone; each row says which version opens it. It is also what makes per-scope erasure legible: destroying the scope destroys every version at once, and the error names the version that was needed.
decode/1 is total. Any binary — truncated, foreign, empty — produces
{:error, %AshVault.Errors.InvalidCiphertext{}} or
{:error, %AshVault.Errors.UnsupportedEnvelope{}}, never an exception.
The AAD, and what it binds
"ashvault:v1|" <> scope <> "|" <> inspect(resource) <> "|" <> to_string(field)This format is frozen. It is a stable, human-inspectable binary rather than
:erlang.term_to_binary/1, because term encoding is not guaranteed stable across OTP
releases and ciphertext has to outlive OTP upgrades.
Binding scope, resource and field into the authentication tag means a ciphertext cannot be
relocated: pasting tenant A's encrypted_email into tenant B's row, or encrypted_ssn
into encrypted_email, or a users blob into contacts, fails authentication with
AshVault.Errors.CiphertextIntegrityFailed rather than silently decrypting into the wrong
place.
The inspect(resource) in there is a deliberate tradeoff: renaming a resource module
invalidates its existing ciphertext. If you rename, re-encrypt first.
AshVault.Context — what it is and is not
%AshVault.Context{resource: module(), field: atom(), ash_context: map() | struct() | nil}It is the non-secret identity of one encrypt-or-decrypt operation: which resource, which field, and an opaque bag of Ash-supplied information from which the scope is resolved.
It is not:
- a carrier of key material, plaintext or ciphertext — it never holds any of the three;
Ash.Scope. Thescopeoption in theash_vaultDSL names anAshVault.Scopemodule — the key scope. That is a different thing fromAsh.Scope/Ash.Scope.ToOpts, which is Ash's mechanism for forwarding actor/tenant to nested calls. They share a word and nothing else.- something you build by hand.
AshVault.Context.Builderis the only place contexts are constructed —from_changeset/3on the write path,from_calculation/3on the read path,from_action_input/2for thekey_lifecyclegeneric actions. Each normalizes its Ash callback struct into one plain map:
%{tenant: tenant, actor: actor, source_context: source_context, phase: :write | :read}That normalization exists because the two Ash callback structs are different shapes, and because of three traps:
source_contextis stale inside a change — it is snapshotted duringfor_create/for_update, so anything a caller sets withAsh.Changeset.set_context/2afterwards never reacheschange/3. The encrypt change rebuilds it fromchangeset.contextinside the hook.- On the write path
changeset.tenantwins (authoritative and current); on the read path the calculation context's:tenantwins, falling back tosource_context[:private][:tenant]. - The tenant here is the raw tenant, never
Ash.ToTenant-normalized — it may be a whole%Organization{}struct. Normalizing it to a stable binary isAshVault.Scopes.AshTenant's job. See Tenant-scoped encryption.
There is no context \\ nil default anywhere in AshVault. A missing tenant is not a
fallback to a global key; it is AshVault.Errors.MissingScope.
Where errors come from
| Layer | Errors it can produce |
|---|---|
| Serializer | SerializationFailed, UnsupportedEnvelope (layer: :plaintext), InvalidCiphertext |
| Scope | MissingScope, InvalidScope |
| Key provider | KeyDestroyed, KeyNotFound, ProviderUnavailable |
| Cipher | CiphertextIntegrityFailed, KeySizeMismatch |
| Envelope | InvalidCiphertext, UnsupportedEnvelope, UnsupportedCipher |
AshVault.Vault.Runtime is the single place raw provider error terms are mapped onto those
structs, which is how :destroyed, :not_found and a transport failure stay three
distinguishable things. See Operations for what to do about each.