# `AshVault.Checks.MacaroonAllows`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/checks/macaroon_allows.ex#L1)

A policy check: true when the actor was authenticated by a macaroon and every
`phase: :authorize` caveat that macaroon carries admits the action being authorized.

    policies do
      policy always() do
        forbid_unless {AshVault.Checks.MacaroonAllows, macaroon: :api}
        authorize_if actor_present()
      end
    end

The actor is the record returned by a verifying read (`:<name>_by_token`, or your
own action using `AshVault.Macaroon.Preparations.Verify`), which carries
`__metadata__.macaroon`. The check evaluates the authorize-phase caveats against an
`AshVault.Macaroon.CheckContext` whose `:action` and `:subject` are the action and
query/changeset being authorized.

## Options

  * `:macaroon` — only accept this macaroon (any macaroon when omitted)
  * `:when_absent` — the answer for an actor without a verified macaroon: `false`
    (default) or `true`. Use `true` to let session-authenticated actors through a
    `forbid_unless`, while macaroon actors are held to their caveats.

> #### Authorize-phase caveats are enforced only here {: .warning}
>
> The verifying read runs `phase: :verify` checks. A `phase: :authorize` caveat is
> enforced by this check and nowhere else: a resource whose policies never use it
> does not restrict a macaroon actor by those caveats. A token holder — or a third
> party handed an attenuated token — cannot tell which resources enforce them, so an
> `actions: ["read"]` caveat is a promise only as good as your policy coverage.
> `AshVault.Verifiers.VerifyMacaroons` warns when the declaring resource itself never
> uses this check; `require_authorize_enforcement? true` on the macaroon refuses such
> tokens unless the verifying caller asserts enforcement.

> #### `when_absent: true` and reloaded actors {: .warning}
>
> The macaroon lives in the actor's `__metadata__`. Anything that re-reads the actor —
> `Ash.reload/2`, `Ash.get/3`, a session that stores only the id and loads the record
> per request — returns a record **without** it, and with `when_absent: true` that
> record passes as an actor that never used a macaroon: every authorize-phase caveat
> silently stops applying. Keep the record the verifying read returned as the actor
> (`Ash.load/3` on it preserves metadata), or use the default `when_absent: false` on
> resources only macaroon actors should reach.

# `eager_evaluate?`

# `init`

# `prefer_expanded_description?`

# `requires_original_data?`

# `strict_check`

# `type`

---

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