# `AshVault.Macaroon.Chain`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/macaroon/chain.ex#L1)

The macaroon signature chain.

    sig_0 = Vault.mac_at!(root_data(token), token.key_version, ctx)
    sig_i = HMAC-SHA256(sig_{i-1}, "ashvault:macaroon:caveat:v1|" <> len64(caveat_i) <> caveat_i)
    token.sig = sig_n

`sig_0` is computed by the vault under the scope's `:mac` key — inside OpenBao for
`AshVault.Macs.OpenBaoTransit` — and is itself bound to the scope, resource and
macaroon name through the vault's associated data. Every later link is computed
locally with `AshVault.Macs.HmacSha256.hmac/2`, keyed by the previous signature: a
holder can append a caveat (extend the chain) but cannot remove one, because that
would need the earlier signature, which the token does not carry.

Each link carries its own domain prefix and a 64-bit length frame, so a chain step can
never collide with the vault's `ashvault:mac:v1|` frame or with any other HMAC an
application computes, and a caveat boundary can never be re-split.

Comparison of the final signature is constant-time (`:crypto.hash_equals/2`).

# `equal?`

```elixir
@spec equal?(term(), term()) :: boolean()
```

Constant-time comparison of two signatures. `false` for anything not 32 bytes.

# `extend`

```elixir
@spec extend(binary(), [binary()]) :: binary()
```

Fold `caveats` onto `sig`, in order.

# `root_data`

```elixir
@spec root_data(AshVault.Macaroon.Envelope.t()) :: binary()
```

The bytes the root signature covers: the prefix, envelope version, scope, key version
and identity, each length-framed.

# `step`

```elixir
@spec step(binary(), binary()) :: binary()
```

One link of the chain: the signature after appending `caveat` to `sig`.

---

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