AshVault.KeyProviders.OpenBao.Transport (AshVault v0.2.0)

Copy Markdown View Source

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

base_options(provider)

@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.

check_legacy_tombstone(provider, name)

@spec check_legacy_tombstone(module(), String.t()) :: :absent | {:error, term()}

Read only the KV tombstone, including during server-retirement migration.

check_tombstone(provider, name)

@spec check_tombstone(module(), String.t()) :: :absent | {:error, term()}

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.

classify_health(provider, body)

@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_tombstone(status, body)

@spec classify_tombstone(integer(), term()) ::
  :destroyed | :absent | {:unavailable, term()}

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_transit_key(status, body)

@spec classify_transit_key(integer(), term()) ::
  :present | :absent | {:unavailable, term()}

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.

create_transit_key(provider, tombstone_name, name, body)

@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.

created_at(provider, meta, version)

@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.

data(body)

@spec data(term()) :: map()

The "data" sub-map of an OpenBao response body, or %{}.

delete_transit_key(provider, name)

@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.

ensure_kv_mount(provider)

@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.

ensure_namespace(provider, name)

@spec ensure_namespace(module(), String.t()) :: :ok | {:error, term()}

Require explicit migration/provisioning before using the escaped binary namespace.

error_message(response)

@spec error_message(term()) :: String.t()

The joined "errors" strings of a response, for substring classification.

get(provider, path)

@spec get(module(), String.t()) :: {:ok, term()} | {:error, Exception.t()}

Issue a GET against the configured OpenBao address.

initialize_retirement(provider)

@spec initialize_retirement(module()) :: :ok | {:error, term()}

Import existing KV tombstones before activating a transactional retirement mount.

key_name(provider, prefix, scope)

@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.

kubernetes_login(provider, options)

@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.

kubernetes_options!(provider)

The validated auth: {:kubernetes, opts} options for provider.

Raises ArgumentError if provider is not configured for Kubernetes auth.

kv_path(provider, suffix)

@spec kv_path(module(), String.t()) :: String.t()

A path under the configured KV mount.

migrate_binary_namespace(provider, scope, rollback? \\ false)

@spec migrate_binary_namespace(module(), binary(), boolean()) ::
  :ok | {:error, term()}

Move an ambiguous exportable scope without exporting key material to the client.

node_status(provider)

@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.

operation(provider, method, path)

@spec operation(module(), atom(), String.t() | nil) :: atom()

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.

post(provider, path, body \\ %{})

@spec post(module(), String.t(), map()) :: {:ok, term()} | {:error, Exception.t()}

Issue a POST against the configured OpenBao address.

read_meta(provider, name)

@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.

read_transit_key(provider, name)

@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}.

request(provider, method, path, body \\ nil)

@spec request(module(), atom(), String.t(), map() | nil) ::
  {:ok, term()} | {:error, Exception.t()}

Issue an arbitrary request, turning every failure mode into AshVault.Errors.ProviderUnavailable.

retire_scope(provider, name, profile \\ :configured)

Atomically retire all purposes of a data key at the server. Never falls back to deletion.

retirement_protocol(provider, initialized?)

@spec retirement_protocol(module(), boolean()) :: :ok | {:error, term()}

Require a compatible transactional plugin, optionally already initialized.

reuse_connections?(provider)

@spec reuse_connections?(module()) :: boolean()

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.

server_retirement?(provider)

@spec server_retirement?(module()) :: boolean()

Whether this provider requires transactional server retirement (default: false).

setup(provider)

@spec setup(module()) :: :ok | {:error, Exception.t()}

Prepare the tombstone store and validate the opted-in retirement backend.

transit_path(provider, suffix)

@spec transit_path(module(), String.t()) :: String.t()

A path under the configured transit mount.

transport_status()

@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.

unavailable(provider, reason, operation \\ nil)

@spec unavailable(module(), term(), atom() | nil) :: Exception.t()

Build the error for a failed request attributed to provider.

A 403 is AshVault.Errors.ProviderForbidden, never AshVault.Errors.ProviderUnavailable: the server answered and refused, which is a policy, credential or addressing fault that retrying cannot fix. Everything else is ProviderUnavailable.

operation names the refused request. For a response from this module's own transport it is recorded on the response and need not be passed.

validate_scope!(provider, scope)

@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.

verify_native_namespace(provider, name)

@spec verify_native_namespace(module(), String.t()) :: :ok | {:error, term()}

Refuse native destruction when legacy keys belong to the exporting provider.

write_tombstone(provider, name, retried? \\ false)

@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.