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

The MAC half of `AshVault.KeyProviders.OpenBaoTransit`: HMAC-SHA256 computed inside
OpenBao, so the `:mac` key never enters the BEAM.

`mac/3` is one `transit/hmac/<name>/sha2-256` call and `verify/4` one
`transit/verify/<name>/sha2-256` call, both pinned to the handle's key version. The
algorithm is in the path rather than left to the server's default, so a default that
changed under an upgrade could not silently change every tag.

## Same frame, same tag as `AshVault.Macs.HmacSha256`

Transit has no associated-data parameter, so the input sent is
`AshVault.Mac.frame(data, aad)` — exactly what `AshVault.Macs.HmacSha256` HMACs. Transit
answers `vault:v<N>:<base64>`; `mac/3` checks that `N` is the version it asked for and
returns the decoded 32 raw bytes. So for the same key bytes the two modules produce the
same tag, which `test/ash_vault/macs/open_bao_transit_test.exs` checks against a live
server by exporting an `hmac` key and comparing.

`verify/4` rebuilds `vault:v<N>:<base64(tag)>` from the handle's version. Rebuilding the
prefix is safe here in a way it is not for ciphertext: the tag is a fixed 32-byte HMAC
whose wire form transit has never varied, and the version comes from the handle the
provider validated, not from the stored bytes.

## Handles only

It accepts only a `:mac` handle from `AshVault.KeyProviders.OpenBaoTransit`
(`{:mac, name, version}`). A data key handle is `{:error, :opaque_key_unsupported}`,
and raw bytes are `{:error, :requires_open_bao_transit_key_provider}` — there is no
transit key name to invent for them.

## Outage versus forgery

`{:error, :invalid_tag}` is returned only when transit answers `200` with
`valid: false`, or when the tag is not 32 bytes (refused before any round trip).
A `400` triggers an authoritative tombstone and key-metadata recheck: erasure returns
`:destroyed`, and a missing key or retired version returns `{:key_not_found, version}`.
The vault translates those into `KeyDestroyed` and `KeyNotFound`. A `403` is
`ProviderForbidden`; ambiguous responses and outages remain `ProviderUnavailable`.

# `decode_tag`

```elixir
@spec decode_tag(term(), pos_integer()) :: {:ok, binary()} | {:error, Exception.t()}
```

Decode transit's `vault:v<N>:<base64>` HMAC into raw bytes, requiring `N == version`.

Public so the parse can be tested without a server.

## Examples

    iex> AshVault.Macs.OpenBaoTransit.decode_tag("vault:v2:" <> Base.encode64(<<0::256>>), 2)
    {:ok, <<0::256>>}

# `id`

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

The stable id, `:openbao_transit_hmac_sha256_v1`.

# `key_bytes`

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

The key size in bytes, `32`. Nominal: this module never sees key bytes.

# `mac`

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

HMAC `AshVault.Mac.frame(data, aad)` through `transit/hmac`, returning 32 raw bytes.

# `verify`

```elixir
@spec verify(binary(), binary(), AshVault.Key.t(), binary()) ::
  :ok | {:error, :invalid_tag} | {:error, term()}
```

Verify a tag through `transit/verify`. `{:error, :invalid_tag}` only for a tag transit
positively rejected, or one that is not 32 bytes.

---

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