# `AshVault.KeyProviders.OpenBao.Transport`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/key_providers/open_bao/transport.ex#L1)

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.

# `base_options`

```elixir
@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`

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

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

# `check_tombstone`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

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

# `delete_transit_key`

```elixir
@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`

```elixir
@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`

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

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

# `error_message`

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

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

# `get`

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

Issue a GET against the configured OpenBao address.

# `initialize_retirement`

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

Import existing KV tombstones before activating a transactional retirement mount.

# `key_name`

```elixir
@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`

```elixir
@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!`

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

# `kv_path`

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

A path under the configured KV mount.

# `migrate_binary_namespace`

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

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

# `node_status`

```elixir
@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`

```elixir
@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`

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

Issue a POST against the configured OpenBao address.

# `read_meta`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

# `retirement_protocol`

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

Require a compatible transactional plugin, optionally already initialized.

# `reuse_connections?`

```elixir
@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?`

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

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

# `setup`

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

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

# `transit_path`

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

A path under the configured transit mount.

# `transport_status`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

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

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

# `write_tombstone`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
