AshVault.Macaroon.Envelope (AshVault v0.2.0)

Copy Markdown View Source

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.

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

t()

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

Functions

decode(token)

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

Decode a token string, strictly. See the moduledoc.

encode(token)

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

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

max_caveats()

@spec max_caveats() :: pos_integer()

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

max_token_bytes()

@spec max_token_bytes() :: pos_integer()

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

valid_prefix?(prefix)

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

Whether prefix is a valid macaroon prefix.

valid_scope?(scope)

@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()

@spec version() :: pos_integer()

The envelope version this build writes, 1.