AshVault.Macaroon.Preparations.Verify (AshVault v0.2.0)

Copy Markdown View Source

Backs the generated :<name>_by_token read action, and any read action you declare yourself to sign in with a macaroon.

read :sign_in_with_token do
  argument :token, :string, allow_nil?: false, sensitive?: true
  get? true
  prepare {AshVault.Macaroon.Preparations.Verify, macaroon: :api, mode: :sign_in}
end

What it does

  1. verifies the token (AshVault.Macaroon.Runtime.verify/4): envelope, prefix, scope, root signature at the stated :mac key version, the caveat chain in constant time, the key-version window, expiry
  2. sets the query's tenant to the token's scope (a :tenant-scoped resource), after the signature has verified and only if the request did not already carry a tenant — one that disagrees is :scope_mismatch
  3. filters to the record the token names, and evaluates revoked_when alongside it
  4. after the read: no record is InvalidMacaroon (:not_found), a revoked_when that is not exactly false is MacaroonRevoked (:record), and every phase: :verify caveat check runs against the loaded record
  5. puts macaroon: %AshVault.Macaroon.Verified{} and using_macaroon?: true into the record's metadata

Options

  • :macaroon — required, the macaroon's name
  • :argument — the token argument, default :token
  • :require_enforcement? — refuse a token that carries phase: :authorize caveats (InvalidMacaroon, :unenforced_caveats) unless the caller asserts they will be enforced with context: %{ash_vault: %{authorize_caveats_enforced?: true}}. Defaults to the macaroon's require_authorize_enforcement?. Turn it on where a verified actor may reach code whose policies do not use AshVault.Checks.MacaroonAllows.
  • :mode — :error (default) returns every failure as an error. :sign_in follows AshAuthentication's sign-in convention: an invalid or revoked token reads as no record ([]), so a plug answers 401. An outage (AshVault.Errors.ProviderUnavailable) is still an error in both modes: an outage must never look like a bad credential, and never like a good one.

The record load is the action's own read, so the resource's policies apply to it. A token-authenticated read usually has no actor yet; authorize the action itself (policy action(:api_by_token) do authorize_if always() end) — the token is the credential.

Summary

Functions

supports(opts)

Callback implementation for Ash.Resource.Preparation.supports/1.

temporal_safe?(opts)

Callback implementation for Ash.Resource.Preparation.temporal_safe?/1.