# `AshVault.KeyProviders.OpenBaoTransit`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/key_providers/open_bao_transit.ex#L1)

An `AshVault.KeyProvider` backed by OpenBao `transit` that **never exports key
material**.

This is the sibling of `AshVault.KeyProviders.OpenBao`, and the difference is the
whole point: that provider exports a scope's raw DEK so an in-process cipher can use
it, and this one does not export anything ever. Encryption and decryption happen
*inside* OpenBao, through `transit/encrypt` and `transit/decrypt`. The key bytes never
become an Elixir term, never land on a process heap, and never appear in a crash dump,
a core file or a `:erlang.system_info(:procs)` dump — because they never leave the
server.

> #### The cost is three network round trips per value {: .warning}
>
> Per *value*, not per query — and three, not one. Measured with a
> `[:finch, :request, :stop]` counter in
> `test/ash_vault/ciphers/open_bao_transit_test.exs`:
>
>   * **encrypt: 3 calls** — tombstone read, `transit/keys` metadata read, then
>     `transit/encrypt`. A scope's very first encrypt adds the key-create call.
>   * **decrypt: 3 calls** — tombstone read, `transit/keys` metadata read, then
>     `transit/decrypt`.
>
> For comparison, measured the same way, `AshVault.KeyProviders.OpenBao` costs 3 on
> encrypt and **2** on decrypt, and `AshVault.KeyProviders.Cached` collapses both to
> **0** on a cache hit. This provider gets nothing from that wrapper: `Cached` caches
> a key only when it `is_binary/1`, so a handle passes through uncached on every call.
> Transit also has batch endpoints, but the `AshVault.Cipher` contract is one value at
> a time, so they go unused.
>
> A page of 50 rows with two encrypted columns is therefore ~300 calls, ~300 ms of
> serialised latency at a 1 ms round trip. Choose this provider when key material in
> BEAM memory is the threat you are actually defending against, and measure before you
> roll it out broadly.

## How it works

A `AshVault.KeyProvider` callback has to return *something* as the key. This one
returns an opaque `AshVault.Key` handle naming the transit key and the version to use:

    %AshVault.Key{ref: {"ashvault_nx_dGVuYW50XzQy", 3}, owner: AshVault.KeyProviders.OpenBaoTransit}

The handle carries no secret — only a name and an integer — and it is a pure,
deterministic function of the scope and the version, so two calls for the same scope
and version are equal terms. `AshVault.Ciphers.OpenBaoTransit` is the only cipher that
understands it; every other cipher returns `{:error, :opaque_key_unsupported}` and
`AshVault.Vault.Runtime` raises `AshVault.Errors.OpaqueKeyUnsupported` naming both
modules. There is deliberately no unwrap path.

    defmodule MyApp.Vault do
      use AshVault.Vault,
        key_provider: AshVault.KeyProviders.OpenBaoTransit,
        cipher: AshVault.Ciphers.OpenBaoTransit
    end

## Configuration

    config :ash_vault, AshVault.KeyProviders.OpenBaoTransit,
      address: "http://127.0.0.1:8200",
      token: {:system, "BAO_TOKEN"},
      transit_mount: "transit",
      kv_mount: "ashvault",
      key_type: "aes256-gcm96",
      receive_timeout: 5_000,
      max_retries: 2,
      reuse_connections: false,
      server_retirement: false

Stock Transit remains the default. `server_retirement: true` requires the initialized
AshVault retirement plugin and transactional server storage. It fences every Transit
operation at the server, including operations using a handle acquired before erasure,
and prevents delayed creates from committing after retirement even if their client
crashes. It never falls back to stock deletion. Live-scope checks add a server-retirement
status request to the round-trip counts above. See
[Server-enforced retirement](openbao-in-kubernetes.md#server-enforced-retirement).

Instead of `:token`, `auth: {:kubernetes, role: "..."}` logs in with the pod's
service account through a supervised token holder, and `:cacertfile` (or
`:connect_options`) trusts a private CA. See
[Running against OpenBao in Kubernetes](openbao-in-kubernetes.md).

`AshVault.Ciphers.OpenBaoTransit` reads this same configuration block — address and
token are looked up under *this* module's key, never carried in the handle.

## The key is verified non-exportable on every metadata read

Creating a transit key that already exists is a **silent no-op** on OpenBao 2.6.2: the
server returns the existing metadata and ignores the `exportable` flag you sent
(verified live). So posting `exportable: false` is not a guarantee — if the key was
already created exportable, by `AshVault.KeyProviders.OpenBao` or by an operator, this
provider would quietly be using exportable key material while its moduledoc promised
otherwise.

`current_key/1` and `get_key/2` therefore *read* `data.exportable` back and refuse
with `AshVault.Errors.ProviderUnavailable` (`reason: {:exportable_key, name}`) if it
is true. The claim in the headline is a checked invariant, not a hope.

This is checked when a key handle is obtained, not on every transit call — flipping a
key to exportable mid-request is not defended against, and cannot be from here.

## Transit key names are deliberately distinct from the exporting provider's

`AshVault.KeyProviders.OpenBao` uses `ashvault_<base64url(scope)>`; this provider uses
`ashvault_nx_<base64url(scope)>` (`nx` for non-exportable). Sharing a name would mean
the first provider to touch a scope decides whether its key is exportable, and the
other one silently inherits that decision.

The consequence is that the two providers hold **separate key material and separate
tombstones** for the same scope, exactly as `AshVault.KeyProviders.Local` and
`AshVault.KeyProviders.OpenBao` do. Migrating between them means re-encrypting, and
erasing a subject who has data under both means destroying under both vaults. See
[Two vaults in one application](two-vaults.md).

The exporting provider escapes ambiguous binary scopes into a versioned prefix.
Before destruction this provider also checks that legacy data and MAC keys are
non-exportable and no exporting-provider lookup key is present. Conflicting or
ambiguous ownership is `ProviderUnavailable`, before writing any tombstone. With
server retirement, the plugin repeats that check inside the retirement transaction.

## The OpenBao policy this provider needs

Verified against openbao 2.6.2. `POST /v1/transit/encrypt/<name>` **creates the key**
if it does not exist, and pinning `key_version` does not stop it. That matters here
because the cipher issues the encrypt from a handle, and the tombstone check lives in
the provider: a handle obtained microseconds before a `destroy/1` would recreate the
deleted transit key on its next encrypt. The recreated key is orphaned — the tombstone
still fails every read closed — but it is key material that should not exist.

Withhold the `create` capability on the encrypt path and OpenBao refuses the
auto-creation with `403` while still allowing encryption of existing keys (verified).
The provider never relies on that auto-creation: `current_key/1` and `current_key/2`
create a missing key explicitly through `transit/keys` before handing out a handle, so
the application token needs `create` there and nowhere else:

    path "transit/keys/ashvault_*"    { capabilities = ["create", "read", "update", "delete"] }
    path "transit/encrypt/ashvault_*" { capabilities = ["update"] }
    path "transit/decrypt/ashvault_*" { capabilities = ["update"] }
    path "ashvault/data/tombstones/*" { capabilities = ["create", "read", "update"] }

(`update` on `transit/keys` covers `rotate` and `config`; `delete` is for `destroy/1`.)
Note there is **no** `transit/export/*` grant, and there must not be one.

A `403` from any of these is `AshVault.Errors.ProviderForbidden`, naming the refused
operation — a configuration fault, not the retryable `ProviderUnavailable`.

> #### Address the active node {: .warning}
>
> Against an HA cluster, `:address` must reach the **active** node only (the Helm
> chart's `<release>-active` Service). Standbys serve reads and policy checks from a
> copy that lags the active node, so an encrypt issued right after the explicit create
> can reach a standby that has not seen the key yet, which treats it as an implicit
> create and, under the policy above, answers `403`. Verified against openbao 2.6.3.
>
> A pooled keep-alive connection would quietly break that precondition: one opened
> while a node was active stays on it after it is demoted, for as long as traffic keeps
> it busy. So by default (`reuse_connections: false`) every request carries
> `connection: close` and opens a new connection, which the `-active` Service routes to
> the current leader. `node_status/0` reports the HA role a request lands on, for a
> boot probe or a gauge. See `AshVault.KeyProviders.OpenBao.Transport.reuse_connections?/1`.

## The `:mac` keyring

The `:mac` purpose (see *Purposes* in `AshVault.KeyProvider`) is a second transit key
per scope, `mac_key_name/1`, created `exportable: false` and verified non-exportable on
every metadata read exactly like the data key. Only its per-version HMAC key is used,
through `transit/hmac` and `transit/verify`; like the exporting provider it is an
`aes256-gcm96` key rather than transit's `hmac` type, because an `hmac`-type key's
metadata carries no creation times (see `AshVault.KeyProviders.OpenBao`). Its handle is
a different shape from a data key handle:

    %AshVault.Key{ref: {:mac, "ashvault_nx_dGVuYW50XzQy.mac", 1}, owner: AshVault.KeyProviders.OpenBaoTransit}

`AshVault.Ciphers.OpenBaoTransit` matches only the two-element data shape, so it refuses
a MAC handle; `AshVault.Macs.OpenBaoTransit` matches only this one, so it refuses a
data handle. The separation of the two keyrings is enforced at the handle, not left to
the caller's discipline. Pair them:

    use AshVault.Vault,
      key_provider: AshVault.KeyProviders.OpenBaoTransit,
      cipher: AshVault.Ciphers.OpenBaoTransit,
      mac: AshVault.Macs.OpenBaoTransit

The application token then also needs:

    path "transit/hmac/*"            { capabilities = ["update"] }
    path "transit/verify/*"          { capabilities = ["update"] }

`transit/hmac` does **not** create a missing key (verified against openbao 2.6.2: it
answers `"encryption key not found"`), so the race described above for
`transit/encrypt` has no MAC counterpart.

## Searchable fields are not supported

This provider deliberately does not implement `c:AshVault.KeyProvider.lookup_key/1`. A
lookup key must be raw bytes in the application process — `AshVault.Lookup` runs HKDF
and HMAC locally — and transit cannot hand out raw bytes by definition. Implementing it
through a second, *exportable* transit key would make the provider's one promise false
for the sake of a feature the exporting provider already does well.

The consequence is loud, not silent: `AshVault.Verifiers.VerifyVault` turns
`searchable?: true` under this provider into a compile-time DSL error naming the
provider, and `AshVault.Errors.LookupUnsupported` is the runtime backstop. Use
`AshVault.KeyProviders.OpenBao` for vaults with searchable fields, or split the
resource across two vaults.

A future provider could compute tokens with `transit/hmac/<key>` and skip local HKDF
entirely, at one more round trip per searchable field per query. That is not built.

## Tombstones and fail-closed behaviour

Identical to `AshVault.KeyProviders.OpenBao`, through the shared
`AshVault.KeyProviders.OpenBao.Transport`: `destroy/1` writes the tombstone *before*
deleting the transit key; a missing KV mount on a read path is
`AshVault.Errors.ProviderUnavailable` and never "not destroyed"; `destroy/1` returns
`:ok` only once the transit key is confirmed absent by a fresh read. An outage is never
reported as erasure, and erasure is never reported as an outage.

# `current_key`

```elixir
@spec current_key(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
```

The current key handle for a scope, creating the transit key (version 1) on first use.

The `:key` is an `AshVault.Key` handle, never bytes. `created_at` comes from the
server's own key metadata — never fabricated, because a key that is always "created
now" is never older than a `max_age` and silently disables every age-based
`AshVault.RotationPolicy`.

# `current_key`

```elixir
@spec current_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose()) ::
  {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
```

The current handle for a scope and purpose. `:data` is `current_key/1`; `:mac` creates
the scope's non-exportable `hmac` transit key on first use.

# `destroy`

```elixir
@spec destroy(AshVault.KeyProvider.scope()) :: :ok | {:error, term()}
```

Tombstone a scope, then irreversibly destroy every key version for it.

The tombstone is committed first, so an interrupted destroy fails closed: a later
`current_key/1` cannot mint a fresh v1 for ciphertext whose key is already gone.
Returns `:ok` only once the transit key is confirmed absent by a fresh read, and a
repeated call resumes cleanup behind an existing tombstone.

Both keyrings go: the data key and the `:mac` key, behind the one tombstone. There is
no lookup key to delete — this provider has none.

# `get_key`

```elixir
@spec get_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.version()) ::
  {:ok, AshVault.Key.opaque()}
  | {:error, :not_found}
  | {:error, :destroyed}
  | {:error, term()}
```

A handle to one specific key version of a scope.

The version is validated against the server's `latest_version` and
`min_decryption_version` **before** a handle is returned. Handing back a handle for a
version that does not exist would push the failure into
`AshVault.Ciphers.OpenBaoTransit`, where a transit `400` becomes
`AshVault.Errors.CiphertextIntegrityFailed` — telling an operator their data was
tampered with, over a key version that was simply never minted.

# `get_key`

```elixir
@spec get_key(
  AshVault.KeyProvider.scope(),
  AshVault.KeyProvider.version(),
  AshVault.KeyProvider.purpose()
) :: {:ok, AshVault.Key.opaque()} | {:error, term()}
```

A handle to one version of a scope's keyring for a purpose, validated against the
server first — see `get_key/2`.

# `handle`

```elixir
@spec handle(String.t(), AshVault.KeyProvider.version()) :: AshVault.Key.opaque()
```

The opaque handle this provider serves for a transit key name and version.

Deterministic and secret-free: `{name, version}`. `AshVault.Key` derives a redacted
`Inspect` that shows only `:owner`, which matters because the name is
`Base.url_encode64/2` of the tenant id and therefore reversible.

# `key_name`

```elixir
@spec key_name(AshVault.KeyProvider.scope()) :: String.t()
```

The transit key name a scope maps to.

Note the `_nx_` infix: this provider's keys are a different namespace from
`AshVault.KeyProviders.OpenBao`'s, on purpose.

    iex> AshVault.KeyProviders.OpenBaoTransit.key_name("tenant_42")
    "ashvault_nx_dGVuYW50XzQy"

# `mac_handle`

```elixir
@spec mac_handle(String.t(), AshVault.KeyProvider.version()) :: AshVault.Key.opaque()
```

The opaque handle this provider serves for a `:mac` key version.

Tagged `{:mac, name, version}` so it cannot be mistaken for a data key handle by
`unwrap/1` — or by `AshVault.Ciphers.OpenBaoTransit`, which goes through it.

# `mac_key_name`

```elixir
@spec mac_key_name(AshVault.KeyProvider.scope()) :: String.t()
```

The transit key name holding a scope's `:mac` keyring.

    iex> AshVault.KeyProviders.OpenBaoTransit.mac_key_name("tenant_42")
    "ashvault_nx_dGVuYW50XzQy.mac"

`.` is outside the base64url alphabet and the prefix, so no data key name can equal
any MAC key name — see `AshVault.KeyProviders.OpenBao.mac_key_name/1`.

# `node_status`

```elixir
@spec node_status() ::
  {:ok, :active | :standby | :sealed | :uninitialized} | {:error, Exception.t()}
```

The HA role of the node a request lands on: `:active`, `:standby`, `:sealed` or
`:uninitialized`. See `AshVault.KeyProviders.OpenBao.Transport.node_status/1`.

# `purposes`

```elixir
@spec purposes() :: [AshVault.KeyProvider.purpose()]
```

The purposes this provider serves: `[:data, :mac]`.

# `rotate`

```elixir
@spec rotate(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}
```

Mint the next key version for a scope. Previous versions stay decryptable.

# `rotate`

```elixir
@spec rotate(AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose()) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}
```

Mint the next key version for a scope and purpose. The `:data` and `:mac` keyrings
are different transit keys and rotate independently.

# `setup`

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

Mount the KV-v2 engine that holds tombstones, if it is not already mounted.

The operator setup step, and the only place the mount is created: the tombstone read
path treats a missing mount as an outage and never provisions it, because a freshly
created, empty tombstone store reports every erased scope as intact.

# `unwrap`

```elixir
@spec unwrap(AshVault.Key.t()) :: {:ok, {String.t(), pos_integer()}} | :error
```

The transit key name and version a handle refers to, for
`AshVault.Ciphers.OpenBaoTransit`.

# `unwrap_mac`

```elixir
@spec unwrap_mac(AshVault.Key.t()) :: {:ok, {String.t(), pos_integer()}} | :error
```

The transit key name and version a `:mac` handle refers to, for
`AshVault.Macs.OpenBaoTransit`. `:error` for anything else, a data handle included.

---

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