The HTTP, configuration, tombstone and error-classification layer shared by the two OpenBao-backed key providers.
AshVault.KeyProviders.OpenBao (which exports raw key material) and
AshVault.KeyProviders.OpenBaoTransit (which never does) differ only in what they do
with a transit key once they have one. Everything underneath — resolving a token
without ever logging it, turning a raised Req step into
AshVault.Errors.ProviderUnavailable, deciding whether a 404 at a tombstone path
means "not destroyed" or "your KV mount is gone" — is identical, and is therefore
written once, here.
Every function takes the calling provider module as its first argument. That
module is both the configuration key (AshVault.KeyProvider.config/1) and the
:provider recorded on every AshVault.Errors.ProviderUnavailable, so an operator
reading an error is told which provider failed, not that "the transport" did.
This module is public because its classification rules are security controls that are tested directly against the exact bodies a live server returns. It is not a stable API for anything outside AshVault.
Summary
Functions
The token-free Req options every request to provider shares: address, timeout and
TLS.
Read only the KV tombstone, including during server-retirement migration.
Read a scope's tombstone, fail-closed.
Classify a sys/health body into the node's HA role.
Classify a raw tombstone-read response into :destroyed, :absent or
{:unavailable, reason}.
Classify a raw transit key metadata read into :present, :absent or
{:unavailable, reason}.
Create a transit key, then recheck the scope's tombstone before releasing the response.
Extract a key version's creation time from transit key metadata.
The "data" sub-map of an OpenBao response body, or %{}.
Delete a transit key, returning :ok only once it is confirmed absent by a fresh
read.
Mount the KV-v2 engine that holds tombstones, if it is not already mounted.
Require explicit migration/provisioning before using the escaped binary namespace.
The joined "errors" strings of a response, for substring classification.
Issue a GET against the configured OpenBao address.
Import existing KV tombstones before activating a transactional retirement mount.
The transit key name a scope maps to, under prefix.
Log in with the Kubernetes auth method: read the service-account JWT, POST it to
/v1/auth/<mount>/login, and return {:ok, client_token, lease_seconds}.
The validated auth: {:kubernetes, opts} options for provider.
A path under the configured KV mount.
Move an ambiguous exportable scope without exporting key material to the client.
The HA role of the node a request to provider lands on, from GET /v1/sys/health.
The operation a request to path with method performs, as recorded on
AshVault.Errors.ProviderForbidden: :read_key, :create_key, :delete_key,
:rotate_key, :configure_key, :encrypt, :decrypt, :hmac, :verify, :export,
:read_tombstone, :write_tombstone, :list_tombstones, :read_retirement,
:retire_scope, :initialize_retirement, :retirement_protocol, :mount,
:login, or :unknown.
Issue a POST against the configured OpenBao address.
Read a transit key's metadata, or {:ok, :missing} when it does not exist.
Read a transit key's presence only: {:ok, :present} or {:ok, :absent}.
Issue an arbitrary request, turning every failure mode into
AshVault.Errors.ProviderUnavailable.
Atomically retire all purposes of a data key at the server. Never falls back to deletion.
Require a compatible transactional plugin, optionally already initialized.
Whether requests to provider reuse pooled keep-alive connections.
Whether this provider requires transactional server retirement (default: false).
Prepare the tombstone store and validate the opted-in retirement backend.
A path under the configured transit mount.
Whether the HTTP transport the OpenBao providers need is actually running.
Build the error for a failed request attributed to provider.
Assert that a scope is a binary, raising ArgumentError naming provider if not.
Refuse native destruction when legacy keys belong to the exporting provider.
Write a scope's tombstone, mounting the KV engine on demand and retrying once.
Functions
@spec base_options(module()) :: {:ok, keyword()} | {:error, Exception.t()}
The token-free Req options every request to provider shares: address, timeout and
TLS.
Redirects are disabled, including the legacy :follow_redirects option. OpenBao
credentials and Kubernetes JWT bodies must never be forwarded to another endpoint.
:cacertfile becomes connect_options: [transport_opts: [cacertfile: path, verify: :verify_peer]], merged over any :connect_options given. Mint keeps its own hostname
check and server name indication on top. verify: :verify_none is refused outright.
A :cacertfile that is not a readable regular file is
{:error, %ProviderUnavailable{reason: {:cacertfile_unreadable, path}}}, checked
before any connection: otherwise Mint's own read raises inside the request and the
failure is indistinguishable from a network outage.
Read only the KV tombstone, including during server-retirement migration.
Read a scope's tombstone, fail-closed.
Returns :absent, {:error, :destroyed}, or
{:error, %AshVault.Errors.ProviderUnavailable{}}. An outage is never reported as
erasure, and erasure is never reported as an outage.
@spec classify_health(module(), term()) :: {:ok, :active | :standby | :sealed | :uninitialized} | {:error, Exception.t()}
Classify a sys/health body into the node's HA role.
Public so the classification is tested against the exact bodies a live server returns.
Classify a raw tombstone-read response into :destroyed, :absent or
{:unavailable, reason}.
Every branch demands a positive identification of the body; a status code alone decides nothing.
Classify a raw transit key metadata read into :present, :absent or
{:unavailable, reason}.
Public because this is the state check destroy/1 requires before it will write a
tombstone and report success, and because a status code alone decides nothing here.
@spec create_transit_key(module(), String.t(), String.t(), map()) :: {:ok, term()} | {:error, term()}
Create a transit key, then recheck the scope's tombstone before releasing the response.
The caller checks the tombstone before reading key metadata. That check alone cannot
fence a create request delayed until after destroy/1 finishes deleting keys. If
erasure won the race, delete this key and confirm absence before reporting :destroyed.
The recheck also runs on failed requests: the server may have committed a create even
when its response was lost. An unavailable tombstone or failed cleanup stays an error.
tombstone_name is always the data key's name, including for MAC and lookup keys.
With server retirement enabled, the transaction fences creation independently of this
client. A late legacy tombstone triggers idempotent server retirement, never separate
key deletion.
@spec created_at(module(), map(), term()) :: {:ok, DateTime.t()} | {:error, Exception.t()}
Extract a key version's creation time from transit key metadata.
Returns {:error, %AshVault.Errors.ProviderUnavailable{}} rather than fabricating a
timestamp. A key whose created_at is always DateTime.utc_now() is never older than
a max_age, so every age-based AshVault.RotationPolicy silently never fires and
nothing anywhere logs a reason.
The "data" sub-map of an OpenBao response body, or %{}.
@spec delete_transit_key(module(), String.t()) :: :ok | {:error, Exception.t()}
Delete a transit key, returning :ok only once it is confirmed absent by a fresh
read.
An operator who closes a deletion ticket on the strength of an :ok deserves the key
to actually be gone. Erasure is decided by state, never by parsing an error message:
"not found" also appears in policy denials, and a denied deletion_allowed call
once reported a successful destroy while the key stayed present and exportable.
@spec ensure_kv_mount(module()) :: :ok | {:error, Exception.t()}
Mount the KV-v2 engine that holds tombstones, if it is not already mounted.
POST /v1/sys/mounts/<path> is not idempotent — an existing mount is
400 "path is already in use" — so idempotency is synthesised here.
Require explicit migration/provisioning before using the escaped binary namespace.
The joined "errors" strings of a response, for substring classification.
@spec get(module(), String.t()) :: {:ok, term()} | {:error, Exception.t()}
Issue a GET against the configured OpenBao address.
Import existing KV tombstones before activating a transactional retirement mount.
@spec key_name(module(), String.t(), AshVault.KeyProvider.scope()) :: String.t()
The transit key name a scope maps to, under prefix.
Transit key names are restricted to [a-zA-Z0-9_.-], so the scope is base64url
encoded. The encoding is total and injective — the padding-free alphabet is used
verbatim, because rewriting - to _ (as an earlier spec said) collapses
Base.url_encode64("ab>") == "YWI-" and Base.url_encode64("ab?") == "YWI_" onto one
name, which would let destroying one tenant crypto-erase another.
Tombstone paths use the same name, so a scope containing / cannot reshape the KV
hierarchy.
@spec kubernetes_login( module(), AshVault.KeyProviders.OpenBao.KubernetesAuth.options() ) :: {:ok, String.t(), non_neg_integer()} | {:error, Exception.t()}
Log in with the Kubernetes auth method: read the service-account JWT, POST it to
/v1/auth/<mount>/login, and return {:ok, client_token, lease_seconds}.
Sends no x-vault-token header and does not retry: the token holder owns backoff.
Every failure is ProviderUnavailable with reason {:kubernetes_auth, reason}; the
response body, which carries the token, never reaches the error.
@spec kubernetes_options!(module()) :: AshVault.KeyProviders.OpenBao.KubernetesAuth.options()
The validated auth: {:kubernetes, opts} options for provider.
Raises ArgumentError if provider is not configured for Kubernetes auth.
A path under the configured KV mount.
Move an ambiguous exportable scope without exporting key material to the client.
@spec node_status(module()) :: {:ok, :active | :standby | :sealed | :uninitialized} | {:error, Exception.t()}
The HA role of the node a request to provider lands on, from GET /v1/sys/health.
{:ok, :active}, {:ok, :standby}, {:ok, :sealed} or {:ok, :uninitialized}, or
{:error, exception} when the node cannot be reached or its answer is not a health
body. Classified from the body (standby, performance_standby, sealed,
initialized), never from the status code alone: the query asks every role to answer
200, so a 429/473 standby code and Req's retry of a 429 never come into it.
Unauthenticated, as the endpoint is: no token is resolved or sent. Never retried. It
travels the same transport as every other request — connection: close included
unless reuse_connections: true — so it reports where a request made now would land,
which is what an operator needs to know.
The operation a request to path with method performs, as recorded on
AshVault.Errors.ProviderForbidden: :read_key, :create_key, :delete_key,
:rotate_key, :configure_key, :encrypt, :decrypt, :hmac, :verify, :export,
:read_tombstone, :write_tombstone, :list_tombstones, :read_retirement,
:retire_scope, :initialize_retirement, :retirement_protocol, :mount,
:login, or :unknown.
Derived from the path, never from the response, and never carrying the key name.
@spec post(module(), String.t(), map()) :: {:ok, term()} | {:error, Exception.t()}
Issue a POST against the configured OpenBao address.
@spec read_meta(module(), String.t()) :: {:ok, map() | :missing} | {:error, Exception.t()}
Read a transit key's metadata, or {:ok, :missing} when it does not exist.
@spec read_transit_key(module(), String.t()) :: {:ok, :present | :absent} | {:error, Exception.t()}
Read a transit key's presence only: {:ok, :present} or {:ok, :absent}.
Issue an arbitrary request, turning every failure mode into
AshVault.Errors.ProviderUnavailable.
Atomically retire all purposes of a data key at the server. Never falls back to deletion.
Require a compatible transactional plugin, optionally already initialized.
Whether requests to provider reuse pooled keep-alive connections.
false (the default) sends connection: close on every request, so each one opens a
new connection and reaches whichever node :address routes to at that moment.
This is what keeps the documented precondition — :address reaches the active
node only — true across an HA leader change. Finch pools have no maximum connection
lifetime, and a connection with steady traffic never goes idle, so a pooled connection
opened while node A was active stays on A after A becomes a standby: indefinitely.
OpenBao 2.5+ standbys serve reads locally from a copy that lags the active node and
forward only writes, so a fresh scope's key create is forwarded and applied, and the
very next read or transit/hmac on that standby finds no key (KeyNotFound, or 403
for an encrypt that the standby treats as an implicit create).
The cost is one TCP (and TLS) handshake per request. reuse_connections: true opts
back into pooling and is safe only when :address is a single, non-HA node, or the
servers run with disable_standby_reads = true.
Anything but a boolean raises ArgumentError: a misspelt value silently choosing
either behaviour would be invisible until the next failover.
Whether this provider requires transactional server retirement (default: false).
@spec setup(module()) :: :ok | {:error, Exception.t()}
Prepare the tombstone store and validate the opted-in retirement backend.
A path under the configured transit mount.
@spec transport_status() :: :ready | {:not_started, :req | :finch}
Whether the HTTP transport the OpenBao providers need is actually running.
A missing OTP application is not an outage, and reporting it as one is the single
most expensive confusion this code can cause: with :req unstarted, every call comes
back looking byte-for-byte like a genuinely unreachable OpenBao, so an operator pages
whoever owns the secrets infrastructure over a missing line in extra_applications.
The check is positive and cheap: Req's default pool is a supervisor registered under
the name Req.Finch, so a live pid there settles it in one Process.whereis/1.
Deliberately not done by matching on the exception's message: several Req/Finch
messages interpolate the request, whose headers carry the token.
@spec validate_scope!(module(), AshVault.KeyProvider.scope()) :: binary()
Assert that a scope is a binary, raising ArgumentError naming provider if not.
Deliberately not :erlang.term_to_binary/1. The external term format is not
guaranteed stable across OTP releases, and it feeds BOTH the transit key name and the
tombstone path: an encoding change would relocate the tombstone (the scope resurrects
with a fresh key) and the key name (every existing ciphertext becomes
AshVault.Errors.KeyNotFound). CORE_SPEC §6 requires scope keys stable across
releases.
Refuse native destruction when legacy keys belong to the exporting provider.
@spec write_tombstone(module(), String.t(), boolean()) :: :ok | {:error, Exception.t()}
Write a scope's tombstone, mounting the KV engine on demand and retrying once.
Creating the store in order to record an erasure cannot lose an erasure, which is why the write path may mount and the read path never may.