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-32prefix 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.
Summary
Functions
Decode a token string, strictly. See the moduledoc.
Encode a token struct. {:error, :malformed} for a struct outside the format.
The maximum number of caveats a token may carry, 32.
The longest token string decode/1 will look at, in bytes.
Whether prefix is a valid macaroon prefix.
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.
The envelope version this build writes, 1.
Types
@type t() :: %AshVault.Macaroon.Envelope{ caveats: [binary()], id: binary(), key_version: pos_integer(), prefix: binary(), scope: binary(), sig: binary(), version: pos_integer() }
Functions
Decode a token string, strictly. See the moduledoc.
Encode a token struct. {:error, :malformed} for a struct outside the format.
@spec max_caveats() :: pos_integer()
The maximum number of caveats a token may carry, 32.
@spec max_token_bytes() :: pos_integer()
The longest token string decode/1 will look at, in bytes.
Whether prefix is a valid macaroon prefix.
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.
@spec version() :: pos_integer()
The envelope version this build writes, 1.