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

The frozen wire format of a macaroon token.

    token   := prefix "_" base64url(payload)        (no padding)
    payload := version::8 = 1
               scope_len::8        scope            1..180 bytes, UTF-8, no control chars
               key_version::32                      >= 1
               id_len::8           id               1..255 bytes
               caveat_count::8                      0..32
               caveat_count × (caveat_len::16  caveat)   1..256 bytes each
               sig::binary-32

`prefix` is 2–32 characters of `[a-z][a-z0-9]*` — deliberately no `_`, so the first
`_` always separates it from the payload (the base64url alphabet itself contains `_`).
A distinctive prefix is what lets secret scanners recognise a leaked token.

The prefix is not inside the payload, but it is bound by the root signature (see
`AshVault.Macaroon.Chain.root_data/1`), so swapping it breaks the token.

## Strictness

`decode/1` fails closed on anything that is not the one canonical encoding: a token
longer than `max_token_bytes/0` (checked before any decoding), non-canonical base64,
an unknown version, a field that runs past the end, trailing bytes, a zero key
version, an oversized caveat list, or a scope with control characters. It returns
`{:error, :malformed}` or `{:error, :unsupported_version}` and nothing more specific:
the details of why a forged token failed to parse are not something to hand back.

# `t`

```elixir
@type t() :: %AshVault.Macaroon.Envelope{
  caveats: [binary()],
  id: binary(),
  key_version: pos_integer(),
  prefix: binary(),
  scope: binary(),
  sig: binary(),
  version: pos_integer()
}
```

# `decode`

```elixir
@spec decode(term()) :: {:ok, t()} | {:error, :malformed | :unsupported_version}
```

Decode a token string, strictly. See the moduledoc.

# `encode`

```elixir
@spec encode(t()) :: {:ok, binary()} | {:error, :malformed}
```

Encode a token struct. `{:error, :malformed}` for a struct outside the format.

# `max_caveats`

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

The maximum number of caveats a token may carry, `32`.

# `max_token_bytes`

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

The longest token string `decode/1` will look at, in bytes.

# `valid_prefix?`

```elixir
@spec valid_prefix?(term()) :: boolean()
```

Whether `prefix` is a valid macaroon prefix.

# `valid_scope?`

```elixir
@spec valid_scope?(term()) :: boolean()
```

Whether `scope` can be carried in a token: 1–180 bytes of UTF-8 without
control characters. Checked on mint and on decode, before any key provider sees it.

180 rather than the field's 255 because a scope becomes a file or key name in
a provider: `AshVault.KeyProviders.Local` names a scope directory with its base64url
encoding plus `.tombstone`, which for 180 bytes is 250 characters — inside every common
filesystem's 255-byte name limit.

# `version`

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

The envelope version this build writes, `1`.

---

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