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

Error structs raised and returned by the AshVault crypto core.

Every error is a [Splode](https://hex.pm/packages/splode) error struct, which means it
is a regular `Exception` that can be raised, but also carries a `:class` (always
`:invalid` here) so it can be aggregated by Ash's error handling.

The modules are:

  * `AshVault.Errors.MissingScope` — the encryption scope could not be resolved
  * `AshVault.Errors.KeyNotFound` — the provider has no such key and no tombstone
  * `AshVault.Errors.KeyDestroyed` — the key was deliberately destroyed (crypto-erasure)
  * `AshVault.Errors.ProviderUnavailable` — transport/backend failure, retryable
  * `AshVault.Errors.ProviderForbidden` — the key store answered and refused the
    request (`403`): a policy, credential or addressing fault, **not** an outage and not
    fixed by retrying the same request
  * `AshVault.Errors.CiphertextIntegrityFailed` — AEAD tag mismatch; the stored
    bytes do not verify. A ciphertext-integrity failure, **not** an access-control one
  * `AshVault.Errors.UnsupportedEnvelope` — envelope version this build cannot parse
  * `AshVault.Errors.UnsupportedCipher` — cipher id not in the registry
  * `AshVault.Errors.InvalidCiphertext` — malformed, truncated or foreign bytes
  * `AshVault.Errors.KeySizeMismatch` — the provider's keys are the wrong size for
    the cipher; a configuration fault, **not** retryable and not tampering
  * `AshVault.Errors.InvalidScope` — an `AshVault.Scope` returned a non-binary key
  * `AshVault.Errors.OpaqueKeyUnsupported` — the provider returned an opaque
    `AshVault.Key` handle and the cipher can only use raw bytes; a configuration
    fault, not retryable and not tampering
  * `AshVault.Errors.LookupUnsupported` — a `searchable?: true` field needs a lookup
    token and the key provider has no `lookup_key/1`; a configuration fault, and
    normally caught at compile time by `AshVault.Verifiers.VerifyVault`
  * `AshVault.Errors.LookupNormalizationFailed` — a searchable field's `normalize:`
    strategy returned something that is not a binary
  * `AshVault.Errors.InvalidMac` — a MAC tag does not verify for this data, context
    and key version. Not an outage, not erasure
  * `AshVault.Errors.PurposeUnsupported` — the key provider cannot serve keys for a
    purpose (such as `:mac`); a configuration fault, not retryable
  * `AshVault.Errors.InvalidMacaroon` — a macaroon is malformed, forged, tampered,
    expired, fails a caveat, or names a record that does not exist
  * `AshVault.Errors.MacaroonRevoked` — a macaroon was valid once and has been revoked:
    by its record, by retiring its `:mac` key version, or by destroying its scope

For MACs the taxonomy reads: `KeyDestroyed` — the scope was erased, so every tag it
ever issued is revoked; `KeyNotFound` — the tag names a key version that does not exist;
`ProviderUnavailable` — retry, nothing was decided; `InvalidMac` — the tag is wrong.

A destroyed key must never surface as `AshVault.Errors.CiphertextIntegrityFailed`:
destruction is checked before any decryption is attempted.

---

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