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

A filesystem-backed `AshVault.KeyProvider` for single-node deployments.

`Local` exists because AshVault's central property — *restoring a PostgreSQL backup must
not resurrect destroyed keys* — only requires the key store to be **a different system
from the database**. A directory on another volume, excluded from the database backup
job, is a legitimate answer for a single-node app. `AshVault.KeyProviders.Memory`
cannot serve that role (it forgets everything on restart) and OpenBao is overkill for
one node.

## Layout

    <root>/
      <scope_dir>/
        meta.json          # {"current": 2, "versions": {"1": "<iso8601>", ...}}
        v1.key             # raw key bytes, mode 0600
        v2.key
        lookup.key         # the non-rotating searchable-field secret, mode 0600
        mac-meta.json      # the :mac keyring's own meta, same shape as meta.json
        mac-v1.key         # :mac key bytes (always 32), mode 0600
      <scope_dir>.tombstone   # presence == scope destroyed

`scope_dir` is `Base.url_encode64(scope, padding: false)` — total, reversible and
filesystem-safe. `scope_dir/1` is public so operators can find a tenant's directory.

The tombstone deliberately sits **beside** the scope directory rather than inside it, so
that deleting (or losing) the directory cannot delete the tombstone.

## Starting it

    # config/runtime.exs
    config :ash_vault, AshVault.KeyProviders.Local,
      root: "/var/lib/my_app/ash_vault_keys",
      key_bytes: 32

    # lib/my_app/application.ex
    children = [MyApp.Repo, AshVault.KeyProviders.Local]

`:root` is required, either as a `start_link/1` option or under that config key.
`start_link/1` also takes `:name` (default `__MODULE__`) and `:key_bytes` (default 32).

## The key root must be initialised explicitly {: .error}

> #### `Local` never creates its own key root {: .error}
>
> Before the provider will start, the root directory must already exist **and**
> contain the sentinel file `.ash_vault_root`. Create both, once, with:
>
>     mix ash_vault.local.init /var/lib/my_app/ash_vault_keys
>
> or, from code, `AshVault.KeyProviders.Local.init_root!/1`.

This is a deliberate, breaking operational requirement, and it exists because the
moduledoc tells you to put the key root on its own volume. If that volume fails to
mount — a reordered systemd unit, a degraded array, an NFS server that is not up
yet — a provider that ran `File.mkdir_p!/1` would create the root on the *underlying*
filesystem, find no tombstones at all, report itself healthy, and mint a fresh
version 1 for every tenant you have ever crypto-erased. No attacker is needed; a
boot-order bug is enough.

The sentinel lives on the mounted volume, so its absence is exactly the signal that
distinguishes "the key store is not there" from "the key store is empty". It is never
created automatically — a fresh install has an empty root too, and auto-creating the
sentinel would make the two indistinguishable again.

Every operation checks that the root and sentinel still identify the store opened
at startup. A missing, unreadable or replaced store returns `ProviderUnavailable`,
including when a mounted volume disappears while the provider is running.

All operations are serialised through a `GenServer`, reads included. Simplicity beats
throughput here; `AshVault.KeyProviders.OpenBao` is the answer for load.

## Operating this provider

> #### The key directory must be excluded from the database backup {: .error}
>
> If the key root and the database land in the same tarball, snapshot or volume clone,
> crypto-erasure is defeated: restoring that backup resurrects both the ciphertext and
> the keys that open it. Keep the key root off the volume you snapshot with the
> database, and exclude it from the database backup job explicitly.

Back the key directory up **separately and deliberately**, with its own retention
policy. This is a real, sharp tradeoff with no free answer:

  * Keeping key backups makes erasure harder — every retained copy of the key root is a
    copy that can resurrect a destroyed tenant, and your retention window is the real
    lifetime of a "destroyed" key.
  * Keeping no key backups makes data loss easy — losing the key root destroys every
    encrypted value in the database, permanently, with no recovery path.

Decide which risk you are underwriting, write it down, and test the restore.

`Local` is **single-node**. Two nodes sharing one NFS or SMB mount will race on
`meta.json` and can mint conflicting versions; use `AshVault.KeyProviders.OpenBao`
for multi-node deployments.

## Durability

Every write is: write to a temp file in the same directory, `fsync` the file, `chmod`
it, then `rename` into place (atomic within a filesystem). A key file always lands
**before** the `meta.json` entry that references it, so an ill-timed crash leaves a
harmless orphan key file rather than a `meta.json` pointing at a missing key — the
latter would be an accidental crypto-erasure, the worst failure this module could have.

> #### Directory fsync is best-effort {: .warning}
>
> OTP offers no way to open a directory for `:file.sync/1` (`:file.open/2` on a
> directory returns `{:error, :eisdir}`), so this provider cannot fsync the containing
> directory after a rename. Durability of the *directory entry* is therefore left to
> the filesystem's own ordering guarantees. The load-bearing property — key file
> durably written before the metadata naming it — does not depend on it.

## Destruction

`destroy/1` writes the **tombstone first**, fsyncs it, and only then overwrites each
`*.key` — `:data`, `:mac` and lookup alike — with random bytes of the same length, fsyncs, unlinks, and removes
`meta.json` and the scope directory. Once the shred completes the tombstone is
rewritten with a `shredded_at`, so an interrupted destroy is visible to an operator.

The ordering is load-bearing. Shredding first and tombstoning second leaves a window
— ENOSPC, EACCES, a read-only remount, a crash — in which the scope has no key
material *and* no tombstone. The next `current_key/1` would see an absent scope and
mint a fresh version 1; existing rows carry `key_version: 1`, so `get_key/2` would
hand back the **new** v1 key and the caller would get
`AshVault.Errors.CiphertextIntegrityFailed` — erasure wearing the costume of tampering.
Tombstone-first fails safe: the worst case is a scope marked destroyed whose key
files linger, and the provider refuses to serve them anyway.

A tombstone is honoured on **presence alone**: its contents are never parsed to
decide whether a scope is destroyed, so a truncated or unreadable tombstone still
means destroyed.

> #### Overwrite-before-unlink guarantees nothing about the media {: .warning}
>
> Overwriting a file's bytes in place is best-effort only. On copy-on-write and
> log-structured filesystems (btrfs, ZFS, APFS, any SSD behind an FTL, and any
> snapshotted or thinly-provisioned volume) the overwrite is written *elsewhere* and
> the original blocks survive until they are reclaimed — if ever. Treat the tombstone
> and the AEAD, not the overwrite, as the mechanism that makes data unreadable. If you
> need media-level erasure, use full-disk encryption and destroy the volume key.

## Error discrimination

An outage must never look like erasure:

  * tombstone present → `{:error, :destroyed}`, for `current_key/1`, `get_key/2` and
    `rotate/1` alike, forever
  * tombstone **unreadable** (`:eacces`, `:eio`, `:estale`, `:eloop`, …) →
    `{:error, %AshVault.Errors.ProviderUnavailable{}}`. A tombstone read that cannot
    complete is never answered with "not destroyed": only a positive `:enoent`
    counts as absence
  * no scope directory, or no `meta.json` → an ordinary absent scope: `current_key/1`
    mints version 1, `get_key/2` returns `{:error, :not_found}`
  * `meta.json` present but corrupt or truncated → `{:error, %AshVault.Errors.ProviderUnavailable{}}`
  * `meta.json` references a version whose key file is missing → `{:error, :not_found}`

Neither corruption nor a missing key file is ever reported as `:destroyed`.

# `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(term(), term()) ::
  {: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()}
```

`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
write its tombstone.

# `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()}
```

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

# `init_root!`

```elixir
@spec init_root!(binary()) :: :ok
```

Create and initialise a key root: the directory itself (mode `0700`) and the
`.ash_vault_root` sentinel the provider refuses to start without.

This is the **operator** step. It is deliberately not something the provider does for
itself — see the moduledoc. It is idempotent, and it never touches existing key
material.

Raises `File.Error` if the directory or the sentinel cannot be created.

# `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 `lookup.key` on first use.

Written with the same crash-safe ordering as a versioned key, gated by the same
tombstone, and shredded by the same `destroy/1` — it ends in `.key`, so
`shred_directory/1` overwrites it before unlinking like any other key file.

It is deliberately absent from `meta.json`: it has no version, and `rotate/1` must
never touch it. See `c:AshVault.KeyProvider.lookup_key/1`.

# `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()}
```

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

# `scope_dir`

```elixir
@spec scope_dir(binary()) :: String.t()
```

The directory name, relative to the root, holding a scope's key material.

    iex> AshVault.KeyProviders.Local.scope_dir("acme")
    "YWNtZQ"

The encoding is `Base.url_encode64/2` without padding: total, reversible and safe on
every filesystem, so operators can map a tenant id to a directory and back.

# `sentinel_file`

```elixir
@spec sentinel_file() :: String.t()
```

The name of the sentinel file that marks a directory as an initialised key root.

# `setup`

```elixir
@spec setup() :: :ok
```

Initialise the configured key root, if it is not initialised already.

The **operator** setup step: exactly `init_root!/1` on the `:root` from configuration,
so a host application that has already written that configuration does not have to dig
it back out to call `init_root!/1` by hand.

    MyApp.Vault.setup()

Idempotent — `init_root!/1` is — but deliberately still explicit: it is the step that
creates the `.ash_vault_root` sentinel, and the sentinel's whole job is to be absent
when the key volume failed to mount. Running it automatically on boot would create it
on the underlying filesystem and hand back a pristine, empty key store. It belongs in
a deploy step, not in a supervision tree.

# `start_link`

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

Start the provider.

Options: `:name` (default `__MODULE__`), `:root` (required, falling back to
`config :ash_vault, AshVault.KeyProviders.Local, root: ...`) and `:key_bytes`.

---

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