# `AshVault.Macaroon.Preparations.Verify`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/macaroon/preparations/verify.ex#L1)

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.

# `supports`

# `temporal_safe?`

---

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