@spec provision(root_vault(), selector(), opts()) ::
  {:ok, Encryptor.Envelope.WrappedKey.t()} | {:error, Encryptor.Error.t()}

Mints a tenant master key and wraps it under the root vault.

32 bytes from the CSPRNG, wrapped into an ordinary Encryptor message with ADR-0003 decision 4's binding as its package-reserved context, returned as an Encryptor.Envelope.WrappedKey. The plaintext does not leave this function.

This is P2 step 1 of ADR-0005's runbook: it mints a version, it never removes one, and it never changes what decryption_keys/2 already returns for versions that exist. Calling it twice concurrently for one tenant can produce two rows claiming the same version; the transaction that closes that race is encryptor_ecto's, and ADR-0003 open question 1 owns the split.

Options

• :reference_subkey - required, 32 bytes. The pinned reference root expanded under "encryptor/v1/tenant-ref", which is what tenant_ref derives from.
• :namespace - the key provider id written into every message header. Defaults to "encryptor-tenant". It may not begin with "aws-kms".
• :version - defaults to 1. ADR-0003's own worked example provisions without naming a version, so first provisioning needs no ceremony; a rotation names n + 1 explicitly.

Why :reference_subkey is an option ADR-0003's opts() did not have

ADR-0003's typespec reads provision(root_vault(), selector(), opts()) with opts() holding only :namespace and :version, and its flow diagram derives the reference inside this function from the root. That was written before ADR-0005 decision 5 split the roots. After the split "a root vault holds only the wrapping subkey as its Static provider material", so a root vault is no longer an input the reference can be derived from - which is exactly why tenant_ref/2's signature was amended at acceptance to take the subkey. provision/3 needs the same value for the same reason, and takes it the same way. This is an extension of the accepted opts() forced by the accepted amendment, and it is flagged rather than assumed.

What it refuses

• :encryption_context in opts - {:reserved_context_key, key}. The binding is not a host option on this path. The host's own static context from the root vault's configuration still merges underneath, because that is ADR-0001 decision 4's behaviour and there is no reason to special-case it.
• a missing :reference_subkey - {:missing_config, [:reference_subkey]}, the same term Encryptor.Vault.Config uses for the same value.
• a :reference_subkey that is not 32 bytes - {:invalid_config, :reference_subkey, :invalid_length}, likewise.
• a :version that is not a positive integer - {:invalid_config, :version, :not_a_positive_integer}.
• a selector that is not a non-empty string - {:invalid_selector, term}. A tenant reference has no meaning for :default.
• a :namespace the engine or this package will not carry in a header - {:invalid_key_descriptor, detail}, from the same checks the vault's keyring builder (lib/encryptor/vault/keyring.ex) runs, so a row is refused at minting rather than at the first encrypt that tries to use it.

@spec rewrap(root_vault(), Encryptor.Envelope.WrappedKey.t()) ::
  {:ok, Encryptor.Envelope.WrappedKey.t()} | {:error, Encryptor.Error.t()}

Re-wraps one wrapping under the root vault's current materials.

This is root rotation, P1 step 3 of ADR-0005's runbook, and it touches no application data: it rewrites one small blob per tenant per live version and leaves every identity column alone, which is why decision 6's split of the two root labels was worth making.

It is built on Encryptor.Vault.rekey/2 and adds nothing cryptographic of its own - ADR-0005 decision 7 settles that rekey/2 stays on the vault precisely because this is its canonical caller. The context is carried across byte for byte, so the returned wrapping carries the same binding, and every identity field of the struct is unchanged. Only :wrapped moves.

Idempotent in effect, not in bytes. A wrapping already under the current root rewraps to an equivalent wrapping: different bytes, because a fresh data key and a fresh IV go into every message, and an identical descriptor on unwrap. A rewrap pass is therefore safe to re-run and safe to resume after a partial failure, which is what makes P1 step 3 recoverable.

The binding is required here for the same reason it is required in unwrap/2: a rekey of a blob that is not a tenant-key wrapping would write a foreign message into the wrapped-key population under a row that claims it is a tenant key.

@spec root_subkey(binary(), Encryptor.Kdf.purpose()) :: binary()

Expands one of ADR-0003 decision 6's labelled subkeys from the supplied root key material.

One line onto Encryptor.Kdf.derive_subkey/3, which is the package's only HKDF implementation. The two purposes decision 6 fixes:

iex> root = :binary.copy(<<0x0B>>, 32)
iex> byte_size(Encryptor.Envelope.root_subkey(root, "root-wrap"))
32

iex> root = :binary.copy(<<0x0B>>, 32)
iex> Encryptor.Envelope.root_subkey(root, "root-wrap") == Encryptor.Envelope.root_subkey(root, "tenant-ref")
false

The parameter is a purpose, and the record can be read two ways

ADR-0003's typespec names the second parameter label and decision 6's table gives the labels in full ("encryptor/v1/root-wrap"), while the same record's worked example calls root_subkey(root, "root-wrap") - a purpose, not a full label. The only reading under which both are true is that the callee composes the "encryptor/v1/" prefix, which is what Encryptor.Kdf.label/1 does and is the reading enc-j4h landed. This function follows it. Flagged rather than treated as settled.

A consequence of the composition is that a purpose containing "/" is refused, so a caller cannot spell an existing label from a different starting point and defeat decision 6's one-way reservation.

Two inputs, after ADR-0005 decision 5

The material is an explicit argument rather than something read from a vault, and ADR-0005 decision 5 leans on exactly that: after the first root rotation a deployment supplies a pinned reference root and a rotating wrapping root, and "a host simply passes different binaries for the two labels". Before the first rotation the two hold the same bytes.

Raises rather than returning {:error, _}, because ADR-0003 specifies a bare binary() return and every way to fail is a caller-supplied constant that is wrong in the source. Every message names the constraint and never the value.

@spec subkey(Encryptor.Key.Aes.t(), Encryptor.Kdf.purpose()) :: binary()

Derives a purpose-separated subkey from a tenant master key.

ADR-0003 decision 7. The tenant master key is a wrapping key first and a derivation root only under an explicit label:

The tenant master key is used directly as RawAes material for the encryption path, and that use is unlabelled because it predates and defines the key. Changing it would invalidate stored ciphertext.

Any other use of a tenant master key derives a subkey by HKDF-Expand(tenant_master_key, info: "encryptor/v1/<purpose>", 32) with a purpose label that is not "root-wrap" or "tenant-ref".

Both root purposes are therefore refused here, and the refusal is the reservation being mechanical rather than remembered:

iex> key = %Encryptor.Key.Aes{namespace: "acme-tenant", name: "t/ref/v1", material: :binary.copy(<<7>>, 32), bits: 256}
iex> byte_size(Encryptor.Envelope.subkey(key, "blind-index"))
32

iex> key = %Encryptor.Key.Aes{namespace: "acme-tenant", name: "t/ref/v1", material: :binary.copy(<<7>>, 32), bits: 256}
iex> Encryptor.Envelope.subkey(key, "root-wrap")
** (ArgumentError) "root-wrap" and "tenant-ref" are the root's purposes and may not be derived from a tenant master key

A derived subkey is never stored. It is recomputed from the tenant master key on demand, so it inherits the master key's shred semantics exactly: destroying the wrapping destroys the index keys too.

What this does not provide is capability separation. A component that can derive index keys under this scheme necessarily holds the tenant master key and can therefore also decrypt. A genuine search-only capability requires an independently random index key with its own wrapping, stored in its own column - a second wrapped key per tenant, not a derivation. ADR-0003 open question 4 was resolved at acceptance in favour of derived subkeys for now, with independently wrapped index keys held open as the recorded upgrade path.

Takes the descriptor rather than the bytes so that a caller reaches for material it already holds legitimately, and so the argument is a type whose inspect/2 redacts it.

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

The keyed, stable, public reference for a tenant identifier.

ADR-0003 decision 5's derivation, amended at acceptance to take the reference subkey rather than a root vault:

tenant_ref =
  Base.url_encode64(
    binary_part(HMAC-SHA256(reference_subkey, selector), 0, 16),
    padding: false
  )

Two properties are what it is bought for. It is stable, so the same tenant always resolves to the same reference and the row can be found. And it is unguessable without the subkey, so a header discloses that two ciphertexts belong to the same tenant without disclosing which tenant that is - which an unkeyed hash of a short slug would not.

The output is not secret: it travels in the clear in every message header, both as the tenant_ref context pair and inside the encrypted data key's name. The input is, and it never reaches a message, a log line, or a failure report.

The derivation lives in one place for all three callers - the vault's start-time known-answer check, the encrypt path's context injection, and this function - because a derivation spelled three times can drift in two of them, and a drifted reference is not a failed check but a message no correct reader can open, against a subkey ADR-0005 consequence four calls effectively permanent.

iex> subkey = :binary.copy(<<0x2A>>, 32)
iex> {:ok, ref} = Encryptor.Envelope.tenant_ref(subkey, "merchant-42")
iex> byte_size(ref)
22
iex> Encryptor.Envelope.tenant_ref(subkey, "merchant-42") == {:ok, ref}
true

:default is refused: a :single vault has no tenant to name.

iex> subkey = :binary.copy(<<0x2A>>, 32)
iex> {:error, error} = Encryptor.Envelope.tenant_ref(subkey, :default)
iex> error.reason
{:invalid_selector, :default}

@spec unwrap(root_vault(), Encryptor.Envelope.WrappedKey.t()) ::
  {:ok, Encryptor.Key.Aes.t()} | {:error, Encryptor.Error.t()}

Unwraps a stored wrapping into the descriptor a provider returns.

The blob is decrypted by the root vault under the reproduced binding, and the result is the %Encryptor.Key.Aes{} of ADR-0002 decision 3 - never a bare binary.

Three failures are worth naming:

• a row whose fields cannot form a descriptor, or a namespace, name or bits the vault would refuse, is {:invalid_key_descriptor, detail}. The detail names the constraint and never the value.
• a blob that does not carry every pair of the binding, at the value this row claims, is :decrypt_failed - checked from the header before any key material is touched. This is what makes a blob copied between tenants, between versions, or in from elsewhere in the application fail here rather than as a wrong key on application data later.
• a blob that does not open under the root vault's current materials is :decrypt_failed too, with the engine's own term in :engine. During a root rotation that is the expected answer for a wrapping the rewrap pass has not reached yet, which is why ADR-0005's P1 keeps the outgoing subkey in the root vault's candidate list until the pass finishes.

unwrap/2 deliberately does not compare the row's name column against the blob. ADR-0003 open question 6 records that cross-check as unsettled: the binding already guarantees the blob belongs to the claimed tenant and version, and making the denormalized columns authoritative is a thing decision 4 explicitly declined to do.