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 ArgumentError instead 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 nil for an encrypt_nil?: false field now always clears the stored ciphertext on an update. encrypt_and_set/4 writes it as an unconditional NULL assignment rather than an attribute change, which Ash dropped as a no-op whenever the caller's record already held nil (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 (new reuse_connections option, default false), so each one reaches the node :address routes 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, or 403 for an implicit-create encrypt). Costs one handshake per request; reuse_connections: true restores pooling for non-HA servers.

Added

  • Consumer usage rules ship with the optional ash_vault_rustler package.

  • ASHVAULT_BACKEND=memory|openbao selects integration tests across Elixir and Go; openbao runs stock Transit and retirement-plugin checks with one selector.

  • Optional server-enforced OpenBao retirement: server_retirement: true on 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 task mix ash_vault.openbao.init_retirement PROVIDER imports existing KV tombstones; existing key material, versions and ciphertext stay compatible.

  • OpenBao.node_status/0, OpenBaoTransit.node_status/0 and OpenBao.Transport.node_status/1: the HA role (:active, :standby, :sealed, :uninitialized) of the node a request lands on, from sys/health, for boot probes and gauges.

  • stored_as: on ordinary encrypt: 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?/4 accepts 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 copy encrypted_<stored_as> (default vault_<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 with legacy:.

  • decrypt_for: [...] on encrypt: SimpleCheck modules, {check, opts} (with optional only: [actions]) or remote &Mod.fun/1 predicates. With legacy:, 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/2 on a legacy: attribute, for an upsert that rewrites a legacy: attribute but keeps its ciphertext, and for stored_as: without legacy:.

  • AshVault.Errors.ProviderForbidden: the key store answered 403. It carries the refused :operation (:encrypt, :hmac, :create_key, :read_key, :read_tombstone, ...) and never the transit key name. AshVault.KeyProviders.OpenBao.Transport.operation/3 derives that operation from a request path.

  • Tests covering a scope's first write under the recommended OpenBao policy, which grants create on transit/keys but not on transit/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 403 is now AshVault.Errors.ProviderForbidden. It was ProviderUnavailable with reason: :forbidden, which callers and metrics treated as a transient outage and retried. A 403 is a policy, credential or addressing fault, and retrying cannot fix it. Match the new struct wherever you matched reason: :forbidden. A 403 on a tombstone read still fails closed. A Kubernetes auth login refused with 403 is still ProviderUnavailable with 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. The OpenBaoTransit policy example now matches what the provider needs: create on transit/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.md and usage-rules/*.md, shipped in the package for usage_rules to sync into an application's agent instructions.

  • Released under the MIT license.

  • Macaroons. A macaroon entity in the ash_vault section declares an attenuable bearer token naming one record (prefix, identity, revoked_when, default_ttl, accepted_key_versions, and caveat name, type, check:, phase: entries). It generates a :mint_<name> generic action and a :<name>_by_token verifying read action, each with a code interface. Guide: Macaroons.

    • Format: prefix_ + base64url of a versioned envelope (scope, :mac key 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 own ashvault:macaroon:caveat:v1| domain prefix, compared in constant time.
    • AshVault.Macaroon.attenuate/2: pure, keyless narrowing by any holder.
    • AshVault.Macaroon.Preparations.Verify, with mode: :sign_in for AshAuthentication-style sign-in actions ([record] or []; outages stay errors).
    • AshVault.Checks.MacaroonAllows: a policy check enforcing phase: :authorize caveats (AshVault.Macaroon.Caveats.ActionIn ships as one).
    • Revocation per record (revoked_when, which must be exactly false), per scope by rotating the :mac keyring past accepted_key_versions (default 1: rotation revokes every outstanding token), and by crypto-erasure (reported as :bad_signature, indistinguishable from forgery by design).
    • Errors AshVault.Errors.InvalidMacaroon and AshVault.Errors.MacaroonRevoked; ProviderUnavailable passes 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_ttl may be a function / AshVault.Macaroon.Ttl module of the mint input, always clamped to the new static max_ttl (required for a function; a :ttl argument above it is refused); accepted_key_versions may be an AshVault.Macaroon.KeyWindow module or MFA of the scope, failing closed to 1; caveat check: takes a module or an inline fn 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 no Vault.mac!/2 call 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 use MacaroonAllows.
    • Token scopes are capped at 180 bytes.
  • AshVault.KeyProviders.Local answers :not_found (not ProviderUnavailable) 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!/4 and current_mac_version!/2, exposed on vaults as mac_at!/3 and mac_key_version!/1 (optional callbacks). mac_at! recomputes a tag at a stated key version with the verify_mac! error taxonomy, and never mints a keyring.

  • AshVault.Mac behaviour (id/0, key_bytes/0, mac/3, verify/4), the authentication sibling of AshVault.Cipher, with two implementations:

  • Key purposes. AshVault.KeyProvider gains optional purposes/0, current_key/2, get_key/3 and rotate/2 callbacks for a per-scope :mac keyring, implemented by Memory, Local, OpenBao, OpenBaoTransit and Cached. :mac keys are 32 random bytes, never the data or lookup key and never derived from either. destroy/1 destroys every purpose under one tombstone.

  • Vault API: mac!/2 returns {key_version, tag}, verify_mac!/4 checks one, and rotate!(scope, purpose: :mac) / AshVault.rotate_key!(vault, scope, ctx, purpose: :mac) rotate the MAC keyring. A new mac: vault option picks the MAC and defaults by provider.

  • Errors: AshVault.Errors.InvalidMac (the tag is wrong) and AshVault.Errors.PurposeUnsupported (the provider has no :mac keyring). KeyDestroyed, KeyNotFound and ProviderUnavailable keep their meanings for MACs: revoked, invalid and retryable.

  • Telemetry: [:ash_vault, :mac, :sign] and [:ash_vault, :mac, :verify] spans, and :purpose on [: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 are ProviderUnavailable with reason {:kubernetes_auth, reason}. Neither the token nor the JWT is logged or put in process status.

  • TLS options for the OpenBao providers: :cacertfile trusts a private CA with peer and hostname verification on, and :connect_options passes through to Req. A missing CA file is ProviderUnavailable with reason {:cacertfile_unreadable, path}, and verify: :verify_none is refused.

  • Guide: Running against OpenBao in Kubernetes.

Compatibility

  • Existing key providers, vaults and configuration keep working unchanged. The arity-1 current_key/1, get_key/2 and rotate/1 callbacks are the :data purpose. A third-party provider without purposes/0 serves :data only.
  • A provider that already defines a current_key/2, get_key/3 or rotate/2 helper (such as a named-server form) and uses @impl elsewhere will now get a missing-@impl warning for it, because those arities are now optional callbacks. Mark them @impl AshVault.KeyProvider, or rename them. Unless the provider also defines purposes/0, AshVault never calls them as purpose callbacks.