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

The AEAD half of `AshVault.KeyProviders.OpenBaoTransit`: encryption and decryption
happen inside OpenBao, so no key material ever enters the BEAM.

Every other `AshVault.Cipher` is a local `:crypto` call over a key the provider handed
it. This one has no key. It receives an `AshVault.Key` handle naming a transit key and
a version, and turns each `encrypt/3` and `decrypt/3` into one HTTP call to
`transit/encrypt` / `transit/decrypt`.

> #### One network round trip per value, *here* {: .warning}
>
> This module contributes one call per `encrypt/3` and one per `decrypt/3`. The value
> costs **three** end to end: `AshVault.KeyProviders.OpenBaoTransit` reads the scope's
> tombstone and the transit key's metadata before handing over the handle this module
> uses. Measured, not estimated — see the `[:finch, :request, :stop]` counter in
> `test/ash_vault/ciphers/open_bao_transit_test.exs`, and
> `AshVault.KeyProviders.OpenBaoTransit` for when that trade is worth making.

## AAD is real here, verified against the live server

`transit/encrypt` accepts `associated_data`, and OpenBao binds it into the GCM tag.
Verified against openbao 2.6.2: decrypting with different associated data, or with
none, returns `400 "cipher: message authentication failed"`. A control probe sending a
genuinely unrecognised parameter comes back with
`warnings: ["Endpoint ignored these unrecognized parameters: [bogus_param]"]`, and
`associated_data` produces no such warning — so it is being consumed, not dropped.

The AAD is `AshVault.Vault.Runtime.build_aad/2` verbatim, base64-encoded for the JSON
body. Cross-tenant, cross-resource and cross-field ciphertext substitution therefore
fail exactly as they do under `AshVault.Ciphers.AES.GCM`. This guarantee is **not**
weakened by moving the AEAD into OpenBao.

`context` (transit's key-derivation input) is deliberately not used: it only applies to
`derived: true` keys and would change what a key *is*, rather than binding data to a
ciphertext.

## What goes in the envelope

The transit ciphertext is a self-describing string, `vault:v<N>:<base64>`. It is stored
**verbatim** in the envelope's `ciphertext` slot, with empty `nonce` and `tag`:

  * The nonce and tag are inside transit's own base64 blob. There is nothing to put in
    those slots, and the frozen v1 envelope layout permits zero-length values for both.
  * Re-synthesising the `vault:v<N>:` prefix from the envelope's `key_version` on the
    way out would mean assuming the prefix format forever. OpenBao already emits other
    shapes for other key classes; storing the server's own string means a future shape
    keeps working with no envelope change.
  * The version is therefore recorded twice — in the envelope header and inside the
    transit string. `decrypt/3` requires them to agree, which costs nothing and turns a
    spliced ciphertext body into a clean refusal before the round trip.

Envelope `cipher` id is `:openbao_transit_v1`, so a value encrypted this way decrypts
through this module forever, even if the vault's default cipher changes later.

## Pairing

This cipher only works with `AshVault.KeyProviders.OpenBaoTransit`. Given raw key bytes
from any other provider it returns `{:error, :requires_open_bao_transit_key_provider}` rather than
inventing a transit key name — there is no correct name to invent. Conversely, every
other cipher declines this provider's handle with `{:error, :opaque_key_unsupported}`.

# `decrypt`

```elixir
@spec decrypt(AshVault.Cipher.payload(), AshVault.Key.t(), binary()) ::
  {:ok, binary()} | {:error, term()}
```

Decrypt through `transit/decrypt`, verifying `aad` as `associated_data`.

Returns `{:error, :auth_failed}` — which `AshVault.Vault.Runtime` reports as
`AshVault.Errors.CiphertextIntegrityFailed` — only for a genuine authentication
failure. Every other failure (a deleted key, a `403`, an unreachable server) is
returned as `AshVault.Errors.ProviderUnavailable`, so an outage is never reported to an
operator as "your data was tampered with".

# `encrypt`

```elixir
@spec encrypt(binary(), AshVault.Key.t(), binary()) ::
  {:ok, AshVault.Cipher.payload()} | {:error, term()}
```

Encrypt through `transit/encrypt`, binding `aad` as `associated_data`.

The encrypt is pinned to the handle's `key_version`, so a rotation racing this call
cannot silently produce a ciphertext under a version the envelope does not name.

# `id`

```elixir
@spec id() :: :openbao_transit_v1
```

The stable cipher id, `:openbao_transit_v1`.

# `key_bytes`

```elixir
@spec key_bytes() :: pos_integer()
```

The key size in bytes, `32`, matching `aes256-gcm96`.

Nominal only: this cipher never sees key bytes. It exists because
`c:AshVault.Cipher.key_bytes/0` is a required callback and
`AshVault.Vault.verify_key_sizes!/2` reads it. `AshVault.KeyProviders.OpenBaoTransit`
deliberately does not export `key_bytes/0`, so that compile-time comparison does not
fire for the supported pairing.

# `parse_version`

```elixir
@spec parse_version(binary()) :: {:ok, pos_integer()} | :error
```

The key version embedded in a transit ciphertext string.

Public so the envelope-versus-transit agreement check can be tested directly.

## Examples

    iex> AshVault.Ciphers.OpenBaoTransit.parse_version("vault:v3:abcdef")
    {:ok, 3}

    iex> AshVault.Ciphers.OpenBaoTransit.parse_version("not a transit ciphertext")
    :error

---

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