All notable changes to AshVault are recorded here. The format follows Keep a Changelog.
Unreleased
0.2.0 - 2026-10-30
Fixed
Legacy dual reads preserve fresh-read field authorization with bounded native sibling reads while denying that authority to caller-supplied record loads. Row correspondence, action inputs, tenant, filters, locks and pagination remain enforced.
Transit MAC configuration faults raise
ArgumentErrorinstead of a retryable outage. Failed MAC operations recheck authoritative state to distinguish erasure, missing or retired versions, policy refusals and unavailable infrastructure.Exporting OpenBao binary scopes cannot collide with the native provider's key namespace. Ambiguous binary scopes use a versioned prefix with an explicit, transactional migration that preserves historical keys, lookup tokens and erasure. Native destruction refuses foreign exportable keys before writing a tombstone.
An explicit
nilfor anencrypt_nil?: falsefield now always clears the stored ciphertext on an update.encrypt_and_set/4writes it as an unconditionalNULLassignment rather than an attribute change, which Ash dropped as a no-op whenever the caller's record already heldnil(a stale record), leaving the old ciphertext in the row. Non-nil writes are unchanged; their random nonce never equals a stored value.OpenBao providers no longer stay pinned to a demoted standby after an HA leader change. Every request now sends
connection: close(newreuse_connectionsoption, defaultfalse), so each one reaches the node:addressroutes to at that moment. Pooled keep-alive connections survived failovers indefinitely, and a fresh scope's first MAC or encrypt then failed against the standby's lagging copy (KeyNotFound/ProviderUnavailable, or403for an implicit-create encrypt). Costs one handshake per request;reuse_connections: truerestores pooling for non-HA servers.
Added
Consumer usage rules ship with the optional
ash_vault_rustlerpackage.ASHVAULT_BACKEND=memory|openbaoselects integration tests across Elixir and Go;openbaoruns stock Transit and retirement-plugin checks with one selector.Optional server-enforced OpenBao retirement:
server_retirement: trueon either provider requires the AshVault external plugin and transactional storage. Retirement atomically removes all key purposes and rejects delayed creates even after a client crash. Stock Transit remains the default. The migration taskmix ash_vault.openbao.init_retirement PROVIDERimports existing KV tombstones; existing key material, versions and ciphertext stay compatible.OpenBao.node_status/0,OpenBaoTransit.node_status/0andOpenBao.Transport.node_status/1: the HA role (:active,:standby,:sealed,:uninitialized) of the node a request lands on, fromsys/health, for boot probes and gauges.stored_as:on ordinaryencrypt: retain an existing ciphertext column and immutable AEAD field binding while keeping the logical public calculation and write argument. Supports native normal/atomic writes and backfill planning without legacy siblings, dual writes or preference reads. Duplicate storage/binding identities are refused.Decryption checks receive normalized tenant, resource, field, phase and source context.
AshVault.DecryptFor.allowed?/4accepts that context while the existing three-argument API and action restrictions retain their behavior.encrypt :field, legacy: Type | {Type, constraints}: expand mode for an attribute already stored by another Ash type. The attribute keeps its column (retyped to the legacy type); AshVault adds the copyencrypted_<stored_as>(defaultvault_<field>), dual-writes it from a global change on every create and update that changes the attribute (atomic paths included), adds it to upserts that rewrite the attribute, and backfills it from the attribute. Values are normalized through the legacy type. See Migrating withlegacy:.decrypt_for: [...]onencrypt: SimpleCheck modules,{check, opts}(with optionalonly: [actions]) or remote&Mod.fun/1predicates. Withlegacy:, admitted actors read the decrypted copy (fail-closed) and everyone else the legacy value. Without it, the decrypt calculation returns%Ash.ForbiddenField{}to everyone it does not admit.Verifier errors for
atomic_update/2on alegacy:attribute, for an upsert that rewrites alegacy:attribute but keeps its ciphertext, and forstored_as:withoutlegacy:.AshVault.Errors.ProviderForbidden: the key store answered403. It carries the refused:operation(:encrypt,:hmac,:create_key,:read_key,:read_tombstone, ...) and never the transit key name.AshVault.KeyProviders.OpenBao.Transport.operation/3derives that operation from a request path.Tests covering a scope's first write under the recommended OpenBao policy, which grants
createontransit/keysbut not ontransit/encrypt. They run against a stub and against a live server (:openbao).
Changed
- Legacy vault sibling loads retain the original read action, arguments, actor, tenant and public context instead of switching to the primary read. Native field policies still apply; the sibling remains a load over fetched records.
- Breaking: an OpenBao
403is nowAshVault.Errors.ProviderForbidden. It wasProviderUnavailablewithreason: :forbidden, which callers and metrics treated as a transient outage and retried. A403is a policy, credential or addressing fault, and retrying cannot fix it. Match the new struct wherever you matchedreason: :forbidden. A403on a tombstone read still fails closed. A Kubernetes auth login refused with403is stillProviderUnavailablewith reason{:kubernetes_auth, :forbidden}, because the token holder retries the login itself.
Documentation
- An HA OpenBao must be addressed through its active node. Standbys serve reads and
policy checks from a lagging copy of the data. An encrypt sent right after AshVault
explicitly creates a scope's key can reach a standby that has not seen the key yet.
The standby treats the encrypt as an implicit create and returns
403. Verified against openbao 2.6.3. TheOpenBaoTransitpolicy example now matches what the provider needs:createontransit/keys, and nothing more on the encrypt path.
0.1.0 - 2026-10-04
First release, published together with ash_vault_rustler 0.1.0.
Added
Usage rules for coding agents:
usage-rules.mdandusage-rules/*.md, shipped in the package forusage_rulesto sync into an application's agent instructions.Released under the MIT license.
Macaroons. A
macaroonentity in theash_vaultsection declares an attenuable bearer token naming one record (prefix,identity,revoked_when,default_ttl,accepted_key_versions, andcaveat name, type, check:, phase:entries). It generates a:mint_<name>generic action and a:<name>_by_tokenverifying read action, each with a code interface. Guide: Macaroons.- Format:
prefix_+ base64url of a versioned envelope (scope,:mackey version, identity, caveats, signature), decoded strictly. The root signature is the vault's MAC at the token's stated key version; each caveat extends an HMAC-SHA256 chain under its ownashvault:macaroon:caveat:v1|domain prefix, compared in constant time. AshVault.Macaroon.attenuate/2: pure, keyless narrowing by any holder.AshVault.Macaroon.Preparations.Verify, withmode: :sign_infor AshAuthentication-style sign-in actions ([record]or[]; outages stay errors).AshVault.Checks.MacaroonAllows: a policy check enforcingphase: :authorizecaveats (AshVault.Macaroon.Caveats.ActionInships as one).- Revocation per record (
revoked_when, which must be exactlyfalse), per scope by rotating the:mackeyring pastaccepted_key_versions(default1: rotation revokes every outstanding token), and by crypto-erasure (reported as:bad_signature, indistinguishable from forgery by design). - Errors
AshVault.Errors.InvalidMacaroonandAshVault.Errors.MacaroonRevoked;ProviderUnavailablepasses through and is never reported as an invalid token. AshVault.Verifiers.VerifyMacaroons: prefix charset, unique identity, resolvable scope, a vault that serves:mac, serializable caveat types and compiled checks.- Computed options:
default_ttlmay be a function /AshVault.Macaroon.Ttlmodule of the mint input, always clamped to the new staticmax_ttl(required for a function; a:ttlargument above it is refused);accepted_key_versionsmay be anAshVault.Macaroon.KeyWindowmodule or MFA of the scope, failing closed to1; caveatcheck:takes a module or an inlinefn value, context -> ... end. - Every failure before the signature verifies (malformed, unknown version, wrong
prefix, unknown or crypto-erased scope, bad chain) is reported to the caller as
InvalidMacaroon{reason: :bad_signature}, with equalized in-process work, so forged tokens cannot enumerate tenants or detect erasure; the precise reason is on the new[:ash_vault, :macaroon, :rejected]telemetry event. A request tenant is compared only after the signature verifies. - The root signature uses the reserved vault field
:"macaroon:<name>", so noVault.mac!/2call for an attribute can serve as a root-signature oracle. require_authorize_enforcement?(DSL) /require_enforcement?(preparation) refuse tokens carrying authorize-phase caveats unless the caller asserts enforcement, and the compiler warns when a macaroon has authorize-phase caveats but the resource's own policies never useMacaroonAllows.- Token scopes are capped at 180 bytes.
- Format:
AshVault.KeyProviders.Localanswers:not_found(notProviderUnavailable) for a scope whose key path exceeds the filesystem's name limit: no key or tombstone can exist there, and a caller-supplied scope must not be able to manufacture an outage.Version-pinned MACs:
AshVault.Vault.Runtime.mac_at!/4andcurrent_mac_version!/2, exposed on vaults asmac_at!/3andmac_key_version!/1(optional callbacks).mac_at!recomputes a tag at a stated key version with theverify_mac!error taxonomy, and never mints a keyring.AshVault.Macbehaviour (id/0,key_bytes/0,mac/3,verify/4), the authentication sibling ofAshVault.Cipher, with two implementations:AshVault.Macs.HmacSha256: HMAC-SHA256 in process, constant-time verification.AshVault.Macs.OpenBaoTransit: HMAC-SHA256 throughtransit/hmacandtransit/verify, so the key never leaves OpenBao.
Key purposes.
AshVault.KeyProvidergains optionalpurposes/0,current_key/2,get_key/3androtate/2callbacks for a per-scope:mackeyring, implemented byMemory,Local,OpenBao,OpenBaoTransitandCached.:mackeys are 32 random bytes, never the data or lookup key and never derived from either.destroy/1destroys every purpose under one tombstone.Vault API:
mac!/2returns{key_version, tag},verify_mac!/4checks one, androtate!(scope, purpose: :mac)/AshVault.rotate_key!(vault, scope, ctx, purpose: :mac)rotate the MAC keyring. A newmac:vault option picks the MAC and defaults by provider.Errors:
AshVault.Errors.InvalidMac(the tag is wrong) andAshVault.Errors.PurposeUnsupported(the provider has no:mackeyring).KeyDestroyed,KeyNotFoundandProviderUnavailablekeep their meanings for MACs: revoked, invalid and retryable.Telemetry:
[:ash_vault, :mac, :sign]and[:ash_vault, :mac, :verify]spans, and:purposeon[:ash_vault, :key, :rotate].Guide: Key purposes and MACs.
Kubernetes auth for the OpenBao providers:
auth: {:kubernetes, role: ..., mount: ..., jwt_path: ...}in place of:token. A token holder supervised by AshVault (AshVault.KeyProviders.OpenBao.KubernetesAuth) logs in with the service-account JWT, caches the client token, and logs in again, re-reading the rotated JWT, at two thirds of the lease. Failures back off exponentially and areProviderUnavailablewith reason{:kubernetes_auth, reason}. Neither the token nor the JWT is logged or put in process status.TLS options for the OpenBao providers:
:cacertfiletrusts a private CA with peer and hostname verification on, and:connect_optionspasses through to Req. A missing CA file isProviderUnavailablewith reason{:cacertfile_unreadable, path}, andverify: :verify_noneis refused.
Compatibility
- Existing key providers, vaults and configuration keep working unchanged. The
arity-1
current_key/1,get_key/2androtate/1callbacks are the:datapurpose. A third-party provider withoutpurposes/0serves:dataonly. - A provider that already defines a
current_key/2,get_key/3orrotate/2helper (such as a named-server form) and uses@implelsewhere will now get a missing-@implwarning for it, because those arities are now optional callbacks. Mark them@impl AshVault.KeyProvider, or rename them. Unless the provider also definespurposes/0, AshVault never calls them as purpose callbacks.