AshVault.Macaroon.Runtime (AshVault v0.2.0)

Copy Markdown View Source

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.

Summary

Types

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

Functions

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.

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

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

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

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.

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.

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 token against a macaroon declaration, up to (not including) the record load.

Types

opts()

@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.

Functions

accepted_key_versions(definition, scope)

@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(resource, definition, caveats, phase, check_context)

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

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

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

identity_attribute(resource, definition)

@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(resource, definition, id, caveats, opts)

@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(definition, requested, input)

@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(resource, verified)

@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(resource, definition, token, opts)

@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.