@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 derive_salt(module(), t(), selector()) ::
  {:ok, binary()} | {:error, Encryptor.Error.t()}

Derives the 32-byte Argon2id salt for one identity, through vault.

Amendment C decision C1. The same call derive/3 makes, under salt_derive_opts/2 - so the salt is a pure function of the vault's :derivation_salt, the selector's key material, and the constants salt_info/1 composes. Nothing in it is random, time-varying, stored, or configurable, which is what enc-ADR-0003 amendment B decision 3 requires of a slow-hash salt and what decision C6 promises about it.

It is a separate function rather than a second return from derive/3 because C5 makes the salt lazy: a slow: false declaration must perform exactly one derivation, and a call that always produced both would spend an HKDF expansion on every index in the package to serve the ones that ask.

The result is the vault's tagged tuple, unwrapped by nothing here, for the reason derive/3 gives: a vault with no :derivation_salt is a fact about the vault rather than about this index's declaration.

@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 salt_derive_opts(t(), selector()) :: keyword()

The Encryptor.Vault.derive/3 options the Argon2id salt derives under.

derive_opts/2 with salt_info/1 in place of info/1, and identical in every other position - amendment C decision C3 puts the salt under the same selector as the index key, and C4 puts it at the same length.

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

C3 is the cheap choice and the stronger one: a deployment-wide salt would make the Argon2id output a function of the plaintext alone, reintroducing one layer in the cross-tenant correlatability decision 3b argues against. Resolving one selector per computation and using it twice is also what makes it impossible for the salt and the key to disagree about which tenant a row belongs to.

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

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

The HKDF info string the per-index Argon2id salt derives under.

Amendment C decision C2: info/1's string with "|slow-salt" appended. Public for the same reason info/1 is - it is a constant the operator's crypto read checks, and a constant only observable through the bytes it produces is a constant nobody reviews.

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

It changes under exactly the changes info/1 changes under and under no others, which is what makes decision C6's claim - that the salt adds no new way to invalidate a column - true rather than merely intended:

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

@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.

@spec slow_params!(module(), t()) :: Encryptor.Kdf.params()

The Argon2id parameters a slow index hashes under, read off vault.

Amendment C decision C5: the parameters are the vault's frozen :slow_hash configuration, read through Encryptor.Vault.config/1, passed through and never interpreted. enc-ADR-0003 amendment B decision 4 completes and validates the set once, at vault start, so there is nothing left here to check and nothing here that could disagree with the primitive about what a complete set is.

A vault that declares no :slow_hash declares no slow parameters, and decision C7 says what this package does with that: it raises Encryptor.Ecto.BlindIndex.DerivationError and computes no value. It does not fall back to a plain HMAC, which would write plain-cost bytes into a column an operator believes is hardened, and it does not invent parameters, which would be this package choosing a cryptographic parameter set.

The refusal is this package's words rather than the vault's - the contrast with derive/3's missing :derivation_salt - because the vault cannot see the declaration that asked. What is wrong is the pairing of a slow: true declaration and a vault configuration that cannot serve it, and a reader sent to the vault alone would find nothing there to fix.