# `AshVault.KeyProviders.Memory`
[🔗](https://github.com/jakeschurch/ash_vault/blob/main/lib/ash_vault/key_providers/memory.ex#L1)

An in-memory `AshVault.KeyProvider`, backed by a `GenServer`.

> #### Development and test only {: .warning}
>
> Every key lives in process memory and dies with the process. There is no
> persistence, no replication and no protection of the key material at rest.
> **Never use this provider in production** — losing the process means losing every
> key, which means losing every encrypted value.

## Adding it to your supervision tree

AshVault deliberately does **not** start this provider for you: applications opt in.
Add it to your own supervisor, usually only outside production:

    # config/dev.exs and config/test.exs
    config :my_app, start_memory_key_provider?: true

    # lib/my_app/application.ex — a runtime flag, not `Mix.env/0`, because `Mix` is
    # not available in a release.
    children =
      [MyApp.Repo] ++
        if Application.get_env(:my_app, :start_memory_key_provider?, false) do
          [AshVault.KeyProviders.Memory]
        else
          []
        end

    Supervisor.start_link(children, strategy: :one_for_one)

It registers under its own module name by default. Pass `name:` to run several
instances (for example one per test):

    start_supervised!({AshVault.KeyProviders.Memory, name: :my_provider})

Note that the `AshVault.KeyProvider` callbacks take no process name, so a vault always
talks to the default-named instance.

## Configuration

    config :ash_vault, AshVault.KeyProviders.Memory, key_bytes: 32

## Destruction semantics

`destroy/1` wipes the scope's key material — the `:data` and `:mac` keyrings and the
lookup key alike — and records a permanent tombstone. Every `current_key`, `get_key`
and `rotate`, for either purpose, and `lookup_key/1` return `{:error, :destroyed}`
afterwards, for the life of the process. Destroying twice is idempotent.

## Purposes

Serves both `:data` and `:mac` (see *Purposes* in `AshVault.KeyProvider`). The two
keyrings are separate maps of separately drawn random bytes, rotated independently.

## Scopes

Scopes must be binaries, matching `AshVault.KeyProviders.Local` and
`AshVault.KeyProviders.OpenBao`. A non-binary scope raises `ArgumentError`: a provider
that silently accepted arbitrary terms would let a custom `AshVault.Scope` pass tests
here and then behave differently — or unsafely — in production.

## Key material never reaches a crash report

`format_status/1` redacts the key table. Without it, any crash in this `GenServer`
emits a SASL report containing every scope's raw key bytes, straight into the log
aggregator and any APM handler attached to it.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `current_key`

```elixir
@spec current_key(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
```

Fetch the current `:data` key for a scope, minting version 1 on first use.

# `current_key`

```elixir
@spec current_key(
  AshVault.KeyProvider.scope() | GenServer.server(),
  AshVault.KeyProvider.purpose() | AshVault.KeyProvider.scope()
) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
```

Two forms, told apart by the first argument — a scope is always a binary, a server
never is:

  * `current_key(scope, purpose)` — the `c:AshVault.KeyProvider.current_key/2`
    callback, against the default-named instance;
  * `current_key(server, scope)` — `current_key/1` against an explicitly named
    instance.

# `current_key`

```elixir
@spec current_key(
  GenServer.server(),
  AshVault.KeyProvider.scope(),
  AshVault.KeyProvider.purpose()
) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
```

Same as `current_key/2` for a purpose, against an explicitly named instance.

# `destroy`

```elixir
@spec destroy(AshVault.KeyProvider.scope()) :: :ok | {:error, term()}
```

Irreversibly destroy every key for a scope — every purpose, and the lookup key — and
tombstone it.

# `destroy`

```elixir
@spec destroy(GenServer.server(), AshVault.KeyProvider.scope()) ::
  :ok | {:error, term()}
```

Same as `destroy/1`, against an explicitly named instance.

# `get_key`

```elixir
@spec get_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.version()) ::
  {:ok, binary()}
  | {:error, :not_found}
  | {:error, :destroyed}
  | {:error, term()}
```

Fetch a specific `:data` key version for a scope.

# `get_key`

```elixir
@spec get_key(term(), term(), term()) ::
  {:ok, binary()}
  | {:error, :not_found}
  | {:error, :destroyed}
  | {:error, term()}
```

Two forms, told apart by the first argument:

  * `get_key(scope, version, purpose)` — the `c:AshVault.KeyProvider.get_key/3`
    callback, against the default-named instance;
  * `get_key(server, scope, version)` — `get_key/2` against a named instance.

# `get_key`

```elixir
@spec get_key(
  GenServer.server(),
  AshVault.KeyProvider.scope(),
  AshVault.KeyProvider.version(),
  AshVault.KeyProvider.purpose()
) ::
  {:ok, binary()}
  | {:error, :not_found}
  | {:error, :destroyed}
  | {:error, term()}
```

Same as `get_key/3` for a purpose, against an explicitly named instance.

# `key_bytes`

```elixir
@spec key_bytes() :: pos_integer()
```

The key size in bytes this provider mints, from config, defaulting to 32.

# `lookup_key`

```elixir
@spec lookup_key(AshVault.KeyProvider.scope()) :: {:ok, binary()} | {:error, term()}
```

Fetch the scope's stable lookup key, minting it on first use.

A separate map, never touched by `rotate/1` and wiped by `destroy/1`. See
`c:AshVault.KeyProvider.lookup_key/1` for why it must not move.

# `lookup_key`

```elixir
@spec lookup_key(GenServer.server(), AshVault.KeyProvider.scope()) ::
  {:ok, binary()} | {:error, term()}
```

Same as `lookup_key/1`, against an explicitly named instance.

# `purposes`

```elixir
@spec purposes() :: [AshVault.KeyProvider.purpose()]
```

The purposes this provider serves: `[:data, :mac]`.

# `rotate`

```elixir
@spec rotate(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}
```

Mint the next `:data` key version for a scope, keeping previous versions fetchable.

# `rotate`

```elixir
@spec rotate(term(), term()) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}
```

Two forms, told apart by the first argument:

  * `rotate(scope, purpose)` — the `c:AshVault.KeyProvider.rotate/2` callback;
  * `rotate(server, scope)` — `rotate/1` against a named instance.

# `rotate`

```elixir
@spec rotate(
  GenServer.server(),
  AshVault.KeyProvider.scope(),
  AshVault.KeyProvider.purpose()
) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}
```

Same as `rotate/2` for a purpose, against an explicitly named instance.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start the provider.

Accepts `:name` (defaults to this module) and `:key_bytes`.

---

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