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

Macaroons for Ash resources: bearer tokens that any holder can **attenuate** — add
caveats that narrow what the token allows — without contacting the issuer, and that
the issuer can revoke at three levels.

    ash_vault do
      vault MyApp.Vault

      macaroon :api do
        prefix "myapp"
        identity :id
        revoked_when expr(not is_nil(revoked_at))
        default_ttl 86_400

        caveat :ip, :string, check: MyApp.Caveats.Ip
        caveat :actions, {:array, :string},
          phase: :authorize,
          check: AshVault.Macaroon.Caveats.ActionIn
      end
    end

generates a `:mint_api` generic action and a `:api_by_token` read action, each with
a code interface. See [Macaroons](macaroons.md) for the full guide, and
`AshVault.Macaroon.Envelope` and `AshVault.Macaroon.Chain` for the frozen format.

This module holds the one operation that needs no key and no resource:
`attenuate/2`.

# `attenuate`

```elixir
@spec attenuate(binary(), keyword() | [{atom() | binary(), term()}]) ::
  {:ok, binary()} | {:error, :malformed | :invalid_caveat}
```

Append caveats to a token, returning a token that allows at most what the original
allowed.

Pure: no vault, no key, no resource. Anyone holding a token can call it, which is the
point — a service can hand a narrower token to a less trusted one. The new caveats
extend the signature chain from the token's own signature, so they cannot be removed
again; the verifier rejects any caveat its macaroon does not declare, or whose value
type disagrees with the declaration.

`caveats` is a keyword list or a list of `{name, value}`; a name may repeat (every
occurrence must hold). Values are strings, integers, booleans, `DateTime`s, or
non-empty lists of strings or of integers.

    {:ok, narrower} = AshVault.Macaroon.attenuate(token, actions: ["read"], ip: "10.0.0.7")

`{:error, :malformed}` for something that is not a token, and
`{:error, :invalid_caveat}` for a name or value outside the format or a result that
would exceed the caveat limits. Attenuating never produces a token the verifier would
reject for its shape.

Attenuating does not check the signature — it cannot. Attenuating a forged token gives
another forged token.

---

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