@spec cache_name(module()) :: atom()

The registered name of a vault's materials cache.

Derived from the vault module, because vaults do not share a cache process: the cache's bounds live on the caching CMM while eviction lives in the cache, and that combination is only coherent when one cache serves one bound set (ADR-0001 decision 3).

@spec config(module()) ::
  {:ok, Encryptor.Vault.Config.t()} | {:error, Encryptor.Error.t()}

A vault's frozen configuration, with the not-started check in front of it.

@spec decrypt(module(), binary(), keyword()) ::
  {:ok, binary()} | {:error, Encryptor.Error.t()}

The decrypt path, behind a vault module's generated decrypt/2.

The order of operations, the value comparison this package performs above the engine, and the reason that comparison cannot be left to the engine are all in the decrypt path's implementation, lib/encryptor/vault/decrypt.ex.

A non-binary ciphertext is a FunctionClauseError rather than an Encryptor.Error, for the same reason encrypt/3's non-binary plaintext is: a value that is not a binary is wrong in the source, not at runtime.

@spec decrypt!(module(), binary(), keyword()) :: binary()

decrypt/3, raising the Encryptor.Error it would have returned.

The struct raised is the same one the non-bang variant returns, so a rescue clause matches on :reason exactly as a case would.

@spec derive(module(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, Encryptor.Error.t()}

The derivation path, behind a vault module's generated derive/2.

ADR-0003 amendment A. The scope is {ikm_selector, salt, info, length}: purpose and opts[:key] are the two halves of the selector, the salt is the vault's :derivation_salt and never the caller's, and :info and :length are the caller's. The derivation path's implementation (lib/encryptor/vault/derive.ex) holds the order and the reasons.

There is no derive!/3. Every other bang variant here exists for an application call site that would rather let a supervisor see the failure; this surface's caller is a library, which has a tagged tuple to thread and an error vocabulary of its own to map onto.

A non-binary purpose is a FunctionClauseError rather than an Encryptor.Error, for the same reason encrypt/3 makes a non-binary plaintext one: it is wrong in the source, not at runtime.

@spec encrypt(module(), binary(), keyword()) ::
  {:ok, binary()} | {:error, Encryptor.Error.t()}

The encrypt path, behind a vault module's generated encrypt/2.

The order of operations, the CMM stack this builds, and the reason the stack order is not configurable are all in the encrypt path's implementation, lib/encryptor/vault/encrypt.ex.

A non-binary plaintext is a FunctionClauseError rather than an Encryptor.Error: the closed reason vocabulary describes what can go wrong with a correct program's arguments at runtime, and a value that is not a binary is wrong in the source.

@spec encrypt!(module(), binary(), keyword()) :: binary()

encrypt/3, raising the Encryptor.Error it would have returned.

The struct raised is the same one the non-bang variant returns, so a rescue clause matches on :reason exactly as a case would.

@spec ensure_provider_started(Encryptor.Vault.Config.t(), Encryptor.Error.operation()) ::
  :ok | {:error, Encryptor.Error.t()}

Checks that a vault's provider is alive, when the provider has a process.

A provider only has a process when it exports child_spec/1, and ADR-0002 decision 1 makes that process an implementation detail of the provider's own callbacks - the vault never talks to it and does not know what name, if any, it registered under. The authoritative answer is therefore the vault supervisor's own child list, where the child's id is the provider module because Encryptor.Vault.Supervisor sets it.

A provider with no child_spec/1 - the common encrypted-column case - skips the check entirely, which is what keeps the supervisor round trip off the hot path for every vault that does not need it.

@spec ensure_started(module(), Encryptor.Error.operation()) ::
  {:ok, Encryptor.Vault.Config.t()} | {:error, Encryptor.Error.t()}

Checks that a vault is running, and reads its frozen configuration.

Both halves matter. The registered name answers whether the supervisor is alive; the :persistent_term entry answers whether a configuration was ever published under it. A vault brought down abnormally can leave the second without the first, and an entry point that read only the frozen struct would encrypt against the configuration of a vault that is no longer there.

@spec lifecycle_name(module()) :: atom()

The registered name of the process that owns a vault's frozen configuration.

@spec ready(module(), Encryptor.Error.operation()) ::
  {:ok, Encryptor.Vault.Config.t()} | {:error, Encryptor.Error.t()}

The lifecycle check every entry point runs before it does anything else.

Returns the frozen configuration when the vault is running and its provider, if it has a process, is alive. Every later bead's encrypt/2, decrypt/2 and rekey/2 is built on this function, which is why the checks live in one place rather than three.

operation is stamped onto the error so an operator reading a log line knows which call failed, not merely that a vault was down.

@spec recycler_name(module()) :: atom()

The registered name of a vault's cache recycler.

Derived the same way the cache name is, and for the same reason: the recycler bounds exactly one vault's cache (ADR-0001 decision 6).

@spec rekey(module(), binary(), keyword()) ::
  {:ok, binary()} | {:error, Encryptor.Error.t()}

The rekey path, behind a vault module's generated rekey/2.

The order of operations, the reason the encryption context comes from the message rather than from the caller, and the reason the vault-side value comparison still runs when the reproduced context is the stored one are all in the rekey path's implementation, lib/encryptor/vault/rekey.ex.

A non-binary ciphertext is a FunctionClauseError rather than an Encryptor.Error, for the same reason encrypt/3 and decrypt/3 make it one: a value that is not a binary is wrong in the source, not at runtime.

@spec rekey!(module(), binary(), keyword()) :: binary()

rekey/3, raising the Encryptor.Error it would have returned.

The struct raised is the same one the non-bang variant returns, so a rescue clause matches on :reason exactly as a case would.

@spec start_link(
  module(),
  keyword()
) :: Supervisor.on_start()

Starts a vault. The generated start_link/1 calls this.

start_opts are layer 4 of the precedence chain. A configuration the vault refuses is an {:error, %Encryptor.Error{}} from here, not a started vault that fails at the first encrypt.

@spec started?(module()) :: boolean()

Whether a vault's supervisor is alive.

This is the liveness half of the not-started check. It reads a registered name and allocates nothing, so an entry point can afford it per call.

@spec stop(module(), term()) :: :ok | {:error, Encryptor.Error.t()}

Stops a running vault.

Stopping erases the frozen configuration, so a subsequent call returns {:vault_not_started, vault} rather than reading a stale struct.

@spec supervised_provider?(module()) :: boolean()

Whether a provider module supplies its own process.

child_spec/1 is optional on Encryptor.Provider, and its presence is the only signal the vault has that a provider wants supervising.

@spec supervisor_name(module()) :: atom()

The registered name of a vault's supervisor.