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

Minting and verifying macaroons for a resource's `macaroon` declaration.

The generated mint action (`AshVault.Macaroon.Actions.Mint`) and the verifying read
preparation (`AshVault.Macaroon.Preparations.Verify`) are thin wrappers over
`mint/4` and `verify/4`. Neither function touches the data layer; loading the record a
token names, and checking its `revoked_when`, is the preparation's job.

## Error taxonomy

`verify/4` returns `{:error, exception}` with exactly one of:

  * `AshVault.Errors.InvalidMacaroon` — the token is wrong (see its `:reason`). Every
    failure before the signature has verified — malformed, unknown version, wrong
    prefix, a scope with no key, a crypto-erased scope, a bad signature — is reported
    as `:bad_signature`, so a forged token learns nothing about which tenants exist or
    were erased. The precise reason is emitted on `[:ash_vault, :macaroon, :rejected]`.
  * `AshVault.Errors.MacaroonRevoked` — `:key_retired` (outside
    `accepted_key_versions`), or `:scope_destroyed` when erasure lands between the
    signature check and the key-window check
  * `AshVault.Errors.ProviderUnavailable` — unchanged from the vault; retry. Never
    turned into "invalid", and never into "valid"
  * a configuration fault from the vault (`PurposeUnsupported`, `KeySizeMismatch`,
    `OpaqueKeyUnsupported`), unchanged

## Order of checks

Everything that can be decided without a key provider is decided first (envelope,
prefix). The request's own tenant is compared with the token's only after the
signature verifies. The root signature is then recomputed at the token's stated
key version — a version-pinned `get_key`, which never mints — and the chain replayed
and compared in constant time. Only after the signature verifies does anything call
the current-version lookup (which mints a keyring on first use), so a forged token
naming an unknown scope cannot make the provider create keys for it.

# `opts`

```elixir
@type opts() :: [
  tenant: term(),
  actor: term(),
  source_context: map(),
  ttl: pos_integer() | :infinity
]
```

`:tenant`, `:actor` and `:source_context` describe the request; `:ttl` (mint only)
overrides `default_ttl`.

# `accepted_key_versions`

```elixir
@spec accepted_key_versions(AshVault.Macaroon.Definition.t(), binary()) ::
  pos_integer() | :all
```

The `accepted_key_versions` window for `scope`: the static value, or the configured
`AshVault.Macaroon.KeyWindow` / MFA's answer. A dynamic answer that is not a positive
integer or `:all`, or that raises, **fails closed to `1`** — only the current key
version verifies — and logs a warning naming the scope by fingerprint only.

# `check_caveats`

```elixir
@spec check_caveats(
  module(),
  AshVault.Macaroon.Definition.t(),
  [{atom(), term()}],
  :verify | :authorize,
  AshVault.Macaroon.CheckContext.t()
) :: :ok | {:error, Exception.t()}
```

Run `phase` caveat checks for a verified token. Returns `:ok` or an
`AshVault.Errors.InvalidMacaroon` naming the first caveat that refused.

# `encode_id`

```elixir
@spec encode_id(term()) :: {:ok, binary()} | :error
```

Encode an identity value as the token's `id` bytes.

# `identity_attribute`

```elixir
@spec identity_attribute(module() | Spark.Dsl.t(), AshVault.Macaroon.Definition.t()) ::
  Ash.Resource.Attribute.t() | nil
```

The attribute a macaroon's `identity` resolves to, or `nil`.

# `mint`

```elixir
@spec mint(
  module(),
  AshVault.Macaroon.Definition.t(),
  binary(),
  [{atom(), term()}],
  opts()
) ::
  {:ok, binary()} | {:error, Exception.t()}
```

Mint a token naming `id` (the record's identity value, already a string) with
`caveats`, a list of `{name, value}` in declaration order with values already cast.

# `resolve_ttl`

```elixir
@spec resolve_ttl(
  AshVault.Macaroon.Definition.t(),
  pos_integer() | nil,
  Ash.ActionInput.t() | nil
) ::
  {:ok, pos_integer() | :infinity} | {:error, Exception.t()}
```

The TTL a token is minted with: `requested` (the `:ttl` argument) when given, else
`default_ttl` — static, or computed from the mint action `input` — always held to
`max_ttl`.

A requested TTL above `max_ttl` is refused (the caller asked for something it may not
have). A computed one is clamped (the function is policy, `max_ttl` the ceiling). A
function that raises or returns anything but a positive integer or `:infinity` refuses
the mint.

# `tenant_for`

```elixir
@spec tenant_for(module(), AshVault.Macaroon.Verified.t()) :: binary() | nil
```

The tenant to run the record load under, for a verified token: the token's scope for a
`:tenant`-scoped resource, `nil` for a `:global` one.

# `verify`

```elixir
@spec verify(module(), AshVault.Macaroon.Definition.t(), term(), opts()) ::
  {:ok, AshVault.Macaroon.Verified.t()} | {:error, Exception.t()}
```

Verify `token` against a macaroon declaration, up to (not including) the record load.

`opts[:tenant]` is the tenant the request already carries, or `nil`. When present it
must agree with the token's scope. Returns the `AshVault.Macaroon.Verified` whose
`:verify`-phase caveats are still to be checked against the loaded record.

---

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