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

Derives the 32-byte index key for one identity, through vault.

The whole construction is the vault's - Encryptor.Vault.derive/3 extracts under the deployment salt, expands under the reserved "blind-index" purpose, and expands again under this record's info. This function names the purpose and the scope and returns what comes back:

selector = Derivation.selector!(derivation, params, :dump)
{:ok, index_key} = Derivation.derive(Payments.Vault, derivation, selector)

The result is the vault's tagged tuple, unwrapped by nothing here. A vault with no :derivation_salt configured answers {:missing_config, [:derivation_salt]}, a %Encryptor.Key.Kms{} descriptor answers {:invalid_key_descriptor, :not_derivable}, and both are the vault's to phrase because both are facts about the vault's configuration rather than about this index's declaration. Translating them into a Encryptor.Ecto.BlindIndex.DerivationError would put this package's words on a misconfiguration it cannot see.

@spec derive_opts(t(), selector()) :: keyword()

The Encryptor.Vault.derive/3 options one identity derives under.

Public for the same reason info/1 is: this is A8's scope, minus the one element that is never the caller's. The salt does not appear because the vault supplies it from its own :derivation_salt and refuses a caller's (enc-ADR-0003 amendment A decision 3) - an option list that could carry a salt is an option list a call site could get wrong.

iex> alias Encryptor.Ecto.BlindIndex.Derivation
iex> Derivation.new!(table: "payments", column: "card_number",
...>   index_name: "card_number_index")
...> |> Derivation.derive_opts({:tenant, "merchant_7f3"})
[
  info: "encryptor_ecto/blind_index/v1|payments|card_number|card_number_index|1",
  length: 32,
  key: "merchant_7f3"
]

A scope: :global index names no key, so a single-key vault's :default selector applies (decision 3c):

iex> alias Encryptor.Ecto.BlindIndex.Derivation
iex> Derivation.new!(table: "signups", column: "email",
...>   index_name: "email_index", scope: :global)
...> |> Derivation.derive_opts(:global)
[info: "encryptor_ecto/blind_index/v1|signups|email|email_index|1", length: 32]

@spec info(t()) :: String.t()

The HKDF info string for one derivation identity.

Public because it is the constant the operator's crypto read checks, and a value that can only be observed through the bytes it produces is a value nobody reviews.

iex> Encryptor.Ecto.BlindIndex.Derivation.new!(
...>   table: "payments", column: "card_number", index_name: "card_number_index")
...> |> Encryptor.Ecto.BlindIndex.Derivation.info()
"encryptor_ecto/blind_index/v1|payments|card_number|card_number_index|1"

A version bump changes it, which is what makes decision 7's rotation rotate anything:

iex> Encryptor.Ecto.BlindIndex.Derivation.new!(
...>   table: "payments", column: "card_number",
...>   index_name: "card_number_index", version: 2)
...> |> Encryptor.Ecto.BlindIndex.Derivation.info()
"encryptor_ecto/blind_index/v1|payments|card_number|card_number_index|2"

@spec new!(keyword()) :: t()

Builds a validated derivation identity.

iex> Encryptor.Ecto.BlindIndex.Derivation.new!(
...>   table: "payments",
...>   column: "card_number",
...>   index_name: "card_number_index"
...> )
%Encryptor.Ecto.BlindIndex.Derivation{
  table: "payments",
  column: "card_number",
  index_name: "card_number_index",
  version: 1,
  scope: :tenant
}

:version defaults to 1, matching index_opts/0's default, so an index that declares no version derives under ...|<index_name>|1 and nothing about an existing declaration changes. :scope defaults to :tenant, matching decision 3a.

Every component is a binary, never an atom. An atom would have to be rendered to reach the info string, and Atom.to_string/1 renders a module alias as "Elixir.Foo" - a rendering that silently changes the derived key for a caller who thought they were passing a name. The conversion belongs at the declaration, where the atom is still visible.

iex> Encryptor.Ecto.BlindIndex.Derivation.new!(
...>   table: "payments", column: "card_number", index_name: :card_number_index)
** (Encryptor.Ecto.BlindIndex.DerivationError) a blind index key could not be derived (table: "payments", column: "card_number", context keys: [], tenant: nil, reason: {:invalid, :index_name, :not_a_non_empty_binary}, index name: nil, index version: 1)

A component may not carry the info string's own separator, for the reason Encryptor.Kdf.label/1 refuses a purpose carrying "/": a component that can spell a separator can spell a different identity's info string from a different starting point, and two indexes the design says are independent collapse onto one key.

iex> Encryptor.Ecto.BlindIndex.Derivation.new!(
...>   table: "payments", column: "card_number", index_name: "a|b")
** (Encryptor.Ecto.BlindIndex.DerivationError) a blind index key could not be derived (table: "payments", column: "card_number", context keys: [], tenant: nil, reason: {:invalid, :index_name, :contains_separator}, index name: "a|b", index version: 1)

@spec outer_label() :: String.t()

The label of the outer expansion, which belongs to encryptor.

iex> Encryptor.Ecto.BlindIndex.Derivation.outer_label()
"encryptor/v1/blind-index"

@spec selector!(t(), field_params(), Encryptor.Ecto.TenantContext.operation()) ::
  selector()

Resolves which scope's key material a derivation needs (decision 3a).

A scope: :global index asks no resolver anything - the choice was made at the field, out loud, and decision 3c is what makes it visible:

iex> alias Encryptor.Ecto.BlindIndex.Derivation
iex> Derivation.new!(table: "identities", column: "email",
...>   index_name: "email_index", scope: :global)
...> |> Derivation.selector!(%{vault: Signups.Vault, tenant: :none,
...>      table: "identities", column: "email"}, :dump)
:global

A scope: :tenant index asks the encrypted field's own strategy, with the field's declared context as the resolver's params - the same call Encryptor.Ecto.Binary makes on the encryption path, so the two cannot disagree about which tenant a row belongs to.

operation is the caller's, because ADR-0003 does not say which of :dump/:load an index computation is and a resolver may legitimately answer differently for a write and a read.