@spec blind(
  input_b64 :: String.t(),
  info_b64 :: String.t(),
  public_key_b64 :: String.t()
) :: {:ok, blind_state()} | {:error, String.t()}

Blind the private input under the public info and the server's public_key (RFC 9497 §3.3.3 Blind).

Returns {:ok, %{blind:, blinded_element:, tweaked_key:}} — keep blind and tweaked_key local; send only blinded_element to the server.

Example

{:ok, %{blinded_element: blinded} = state} =
  MetamorphicCrypto.Poprf.blind(input_b64, info_b64, server_public_b64)

@spec blind_evaluate(
  secret_key_b64 :: String.t(),
  blinded_element_b64 :: String.t(),
  info_b64 :: String.t()
) :: {:ok, {String.t(), String.t()}} | {:error, String.t()}

The server-side blind evaluation (RFC 9497 §3.3.3 BlindEvaluate): evaluate a client's blinded_element under secret_key tweaked by the public info.

Returns {:ok, {evaluated_element_b64, dleq_proof_b64}} or {:error, reason}. The server learns nothing about the input behind the blinded element.

@spec blind_evaluate_with_random(
  secret_key_b64 :: String.t(),
  blinded_element_b64 :: String.t(),
  info_b64 :: String.t(),
  random_b64 :: String.t()
) :: {:ok, {String.t(), String.t()}} | {:error, String.t()}

KAT-only blind_evaluate/3 with an explicit DLEQ nonce (deterministic), for cross-language known-answer tests.

@spec blind_with_scalar(
  input_b64 :: String.t(),
  info_b64 :: String.t(),
  public_key_b64 :: String.t(),
  blind_b64 :: String.t()
) :: {:ok, blind_state()} | {:error, String.t()}

KAT-only blind/3 with an explicit blind scalar (deterministic), for cross-language known-answer tests. Production callers use blind/3.

@spec derive_key_pair(seed_b64 :: String.t(), key_info_b64 :: String.t()) ::
  {:ok, %{secret_key: String.t(), public_key: String.t()}}
  | {:error, String.t()}

Derive a POPRF keypair deterministically from a 32-byte seed and a public key_info string (RFC 9497 §3.2.1 DeriveKeyPair) — how an operator turns a managed master secret into a stable deployment evaluation key.

Returns {:ok, %{secret_key: base64, public_key: base64}} or {:error, reason}.

Example

{:ok, %{secret_key: sk, public_key: pk}} =
  MetamorphicCrypto.Poprf.derive_key_pair(seed_b64, key_info_b64)

@spec evaluate(
  secret_key_b64 :: String.t(),
  input_b64 :: String.t(),
  info_b64 :: String.t()
) :: {:ok, String.t()} | {:error, String.t()}

The non-oblivious server-side evaluation (RFC 9497 §3.3.3 Evaluate): compute the output directly from secret_key and the cleartext input — how an operator derives indices for inputs it already holds (directory construction). Produces exactly the output a client derives obliviously via blind/3 → blind_evaluate/3 → finalize/7.

Returns {:ok, output_b64} or {:error, reason}.

@spec finalize(
  input_b64 :: String.t(),
  blind_b64 :: String.t(),
  evaluated_element_b64 :: String.t(),
  blinded_element_b64 :: String.t(),
  proof_b64 :: String.t(),
  info_b64 :: String.t(),
  tweaked_key_b64 :: String.t()
) :: {:ok, String.t()} | :invalid | {:error, String.t()}

The client-side completion (RFC 9497 §3.3.3 Finalize): verify the server's DLEQ proof against the tweaked_key, unblind, and return the 64-byte output.

Distinguishes a cryptographic rejection from a structural error:

• {:ok, output_b64} — the proof is valid; output_b64 is the PRF output.
• :invalid — a cryptographic rejection (wrong key, wrong info, tampered evaluation, or a forged proof). The inputs were well-formed but the proof does not verify.
• {:error, reason} — a structural failure (wrong lengths, invalid base64 or a non-canonical encoding).

@spec generate_keypair() :: %{secret_key: String.t(), public_key: String.t()}

Generate a fresh POPRF keypair from the OS CSPRNG.

Returns %{secret_key: base64, public_key: base64}. Intended for tests and tooling; a deployment derives its stable key with derive_key_pair/2.

Example

%{secret_key: sk, public_key: pk} = MetamorphicCrypto.Poprf.generate_keypair()

@spec public_key(secret_key_b64 :: String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

Derive the base64 public key for a base64 secret_key.

Returns {:ok, public_key_b64} or {:error, reason} (wrong length / invalid base64 / non-canonical scalar).