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

Introspection for the `AshVault` extension.

`Spark.InfoGenerator` generates the raw option readers — `ash_vault_vault/1` and
`ash_vault_vault!/1`, `ash_vault_scope/1`, `ash_vault_attributes/1`,
`ash_vault_decrypt_by_default/1`, `ash_vault_encrypt_nil?/1`, `ash_vault_scope_owner?/1`,
`ash_vault_options/1`, `ash_vault_key_lifecycle_rotate/1`, `ash_vault_key_lifecycle_destroy/1`
— plus `ash_vault/1`, which returns the `encrypt` entities.

Note the generator's naming rules: entity readers are named after the *section path*
(hence `ash_vault/1`, not `ash_vault_encrypt/1`), `?`-suffixed options get only a
predicate function with no bang variant, and options with a non-nil default never
return `:error`.

On top of those this module adds the helpers the extension itself uses.

# `ash_vault`

```elixir
@spec ash_vault(dsl_or_extended :: module() | map()) :: [struct()]
```

ash_vault DSL entities

# `ash_vault_attributes`

```elixir
@spec ash_vault_attributes(dsl_or_extended :: module() | map()) ::
  {:ok, [atom()]} | :error
```

Shorthand for a list of `encrypt` entities with default options.

# `ash_vault_attributes!`

```elixir
@spec ash_vault_attributes!(dsl_or_extended :: module() | map()) ::
  [atom()] | no_return()
```

Shorthand for a list of `encrypt` entities with default options.

# `ash_vault_decrypt_by_default`

```elixir
@spec ash_vault_decrypt_by_default(dsl_or_extended :: module() | map()) ::
  {:ok, [atom()]} | :error
```

Encrypted fields whose decrypt calculation is loaded automatically.

# `ash_vault_decrypt_by_default!`

```elixir
@spec ash_vault_decrypt_by_default!(dsl_or_extended :: module() | map()) ::
  [atom()] | no_return()
```

Encrypted fields whose decrypt calculation is loaded automatically.

# `ash_vault_encrypt_nil?`

```elixir
@spec ash_vault_encrypt_nil?(dsl_or_extended :: module() | map()) :: boolean()
```

Encrypt `nil` rather than storing SQL NULL. Overridable per field.

# `ash_vault_key_lifecycle_destroy`

```elixir
@spec ash_vault_key_lifecycle_destroy(dsl_or_extended :: module() | map()) ::
  {:ok, atom()} | :error
```

Name of a generic action that destroys this scope's keys.

# `ash_vault_key_lifecycle_destroy!`

```elixir
@spec ash_vault_key_lifecycle_destroy!(dsl_or_extended :: module() | map()) ::
  atom() | no_return()
```

Name of a generic action that destroys this scope's keys.

# `ash_vault_key_lifecycle_options`

```elixir
@spec ash_vault_key_lifecycle_options(dsl_or_extended :: module() | map()) :: %{
  required(atom()) =&gt; any()
}
```

ash_vault.key_lifecycle DSL options

Returns a map containing the and any configured or default values.

# `ash_vault_key_lifecycle_rotate`

```elixir
@spec ash_vault_key_lifecycle_rotate(dsl_or_extended :: module() | map()) ::
  {:ok, atom()} | :error
```

Name of a generic action that rotates this scope's key.

# `ash_vault_key_lifecycle_rotate!`

```elixir
@spec ash_vault_key_lifecycle_rotate!(dsl_or_extended :: module() | map()) ::
  atom() | no_return()
```

Name of a generic action that rotates this scope's key.

# `ash_vault_options`

```elixir
@spec ash_vault_options(dsl_or_extended :: module() | map()) :: %{
  required(atom()) =&gt; any()
}
```

ash_vault DSL options

Returns a map containing the and any configured or default values.

# `ash_vault_scope`

```elixir
@spec ash_vault_scope(dsl_or_extended :: module() | map()) ::
  {:ok, (:global | :tenant) | module()} | :error
```

The *key* scope: `:tenant` (`AshVault.Scopes.AshTenant`), `:global` (`AshVault.Scopes.Global`), or an `AshVault.Scope` module. Unrelated to `Ash.Scope`.

# `ash_vault_scope!`

```elixir
@spec ash_vault_scope!(dsl_or_extended :: module() | map()) ::
  ((:global | :tenant) | module()) | no_return()
```

The *key* scope: `:tenant` (`AshVault.Scopes.AshTenant`), `:global` (`AshVault.Scopes.Global`), or an `AshVault.Scope` module. Unrelated to `Ash.Scope`.

# `ash_vault_scope_owner?`

```elixir
@spec ash_vault_scope_owner?(dsl_or_extended :: module() | map()) :: boolean()
```

This resource *is* the scope (the tenant/organization). Required for `key_lifecycle`.

# `ash_vault_vault`

```elixir
@spec ash_vault_vault(dsl_or_extended :: module() | map()) ::
  {:ok, module() | mfa() | (any(), any() -&gt; any())} | :error
```

The vault to encrypt and decrypt with. A module using `AshVault.Vault`, an MFA, or a `fun/2` of `(resource, context) -> vault_module`.

# `ash_vault_vault!`

```elixir
@spec ash_vault_vault!(dsl_or_extended :: module() | map()) ::
  (module() | mfa() | (any(), any() -&gt; any())) | no_return()
```

The vault to encrypt and decrypt with. A module using `AshVault.Vault`, an MFA, or a `fun/2` of `(resource, context) -> vault_module`.

# `encrypt_entities`

```elixir
@spec encrypt_entities(module() | Spark.Dsl.t()) :: [AshVault.Encrypted.t()]
```

The `encrypt` entities of a resource, without the `attributes` sugar.

`ash_vault/1` returns every entity in the section — `macaroon`s too — so anything that
wants encrypted fields reads them through here.

# `encrypt_nil?`

```elixir
@spec encrypt_nil?(module() | Spark.Dsl.t(), atom() | AshVault.Encrypted.t()) ::
  boolean()
```

Whether `nil` is encrypted for a field, resolving the per-field override against the
section-level default.

# `encrypted_field`

```elixir
@spec encrypted_field(module() | Spark.Dsl.t(), atom()) ::
  AshVault.Encrypted.t() | nil
```

One encrypted field by name, or `nil`.

# `encrypted_field_names`

```elixir
@spec encrypted_field_names(module() | Spark.Dsl.t()) :: [atom()]
```

The names of every encrypted field of a resource.

# `encrypted_fields`

```elixir
@spec encrypted_fields(module() | Spark.Dsl.t()) :: [AshVault.Encrypted.t()]
```

Every encrypted field of a resource, as `%AshVault.Encrypted{}` structs.

This merges the `attributes [...]` sugar with the explicit `encrypt` entities, so it
returns the same answer before and after `AshVault.Transformers.ExpandAttributes` has
run. Explicit entities win over sugar of the same name, and order is
entities-then-sugar.

# `legacy_fields`

```elixir
@spec legacy_fields(module() | Spark.Dsl.t()) :: [AshVault.Encrypted.t()]
```

The `encrypt ..., legacy: ...` entities of a resource, as declared (named after the
legacy attribute).

# `legacy_type`

```elixir
@spec legacy_type(AshVault.Encrypted.t()) :: {module(), keyword()}
```

A `legacy:` field's legacy type and constraints.

# `macaroon`

```elixir
@spec macaroon(module() | Spark.Dsl.t(), atom()) ::
  AshVault.Macaroon.Definition.t() | nil
```

One `macaroon` by name, or `nil`.

# `macaroons`

```elixir
@spec macaroons(module() | Spark.Dsl.t()) :: [AshVault.Macaroon.Definition.t()]
```

Every `macaroon` declared on a resource.

# `normalize`

```elixir
@spec normalize(module() | Spark.Dsl.t(), atom() | AshVault.Encrypted.t()) ::
  AshVault.Lookup.normalize()
```

The `normalize:` strategy configured for a field, defaulting to `:none`.

# `scope_module`

```elixir
@spec scope_module(module() | Spark.Dsl.t()) :: module()
```

The `AshVault.Scope` module for a resource's key scope.

# `searchable?`

```elixir
@spec searchable?(module() | Spark.Dsl.t(), atom()) :: boolean()
```

Whether one field of a resource is searchable.

# `searchable_fields`

```elixir
@spec searchable_fields(module() | Spark.Dsl.t()) :: [AshVault.Encrypted.t()]
```

Every searchable field of a resource, as `%AshVault.Encrypted{}` structs.

# `stored_as`

```elixir
@spec stored_as(AshVault.Encrypted.t()) :: atom()
```

The stable storage and cryptographic binding name of an encrypted field.

# `stored_as`

```elixir
@spec stored_as(module() | Spark.Dsl.t(), atom()) :: atom()
```

Resolve a logical field to its stable storage and binding name.

# `vault!`

```elixir
@spec vault!(module() | Spark.Dsl.t(), term()) :: module()
```

The vault module for a resource, resolving the `fun/2` and MFA forms against the
callback context.

The context handed here is always the **normalized** `ash_context` map built by
`AshVault.Context.Builder` — `%{tenant:, actor:, source_context:, phase:}` — so a
dynamic vault sees one shape on the write path, the read path and the lifecycle
actions alike, rather than three different Ash callback structs.

---

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