@spec combined_root(directory()) :: {:ok, String.t()} | {:error, String.t()}

The current combined-tree root (the published directory root), base64-encoded.

Returns {:ok, root_b64} or {:error, reason} (an empty directory has no root).

@spec directory_open(suite(), context :: String.t(), vrf_secret_b64 :: String.t()) ::
  {:ok, directory()} | {:error, String.t()}

Open a per-namespace directory on suite from an existing VRF secret key, committing values under context, returning an opaque, empty directory/0 resource.

Replay the namespace's versions into it with update/5 to reconstruct the current directory. Returns {:ok, directory} or {:error, reason} (an unknown suite or a structurally invalid secret key).

@spec directory_vrf_public(directory()) :: {:ok, String.t()} | {:error, String.t()}

The VRF public key (base64) relying parties use to verify this directory's proofs. Returns {:ok, vrf_public_b64}.

@spec generate_vrf_key(suite()) ::
  {:ok, {String.t(), String.t()}} | {:error, String.t()}

Generate a fresh VRF keypair for suite.

Returns {:ok, {secret_b64, public_b64}}. The secret_b64 is per-namespace operator infrastructure — persist it securely and pass it to directory_open/3; it is not user key material and not a signing key. The public_b64 is published so relying parties can verify proofs.

@spec prove_search(directory(), label_b64 :: String.t()) ::
  {:ok, {:present, String.t(), String.t()}}
  | {:ok, {:absent, String.t()}}
  | {:error, String.t()}

Produce a greatest-version search proof for label against the current log head.

Returns {:ok, {:present, value_b64, proof_b64}} when the label has a value, {:ok, {:absent, proof_b64}} when it does not, or {:error, reason} (an empty directory or VRF failure). The returned proof_b64 verifies via verify_search/6 against the published directory_vrf_public/1 key and combined_root/1.

@spec suite_id(suite()) :: 0..65535

The §15.1 suite_id (u16) for a suite atom.

Examples

iex> MetamorphicLog.Keytrans.suite_id(:kt128_sha256_p256)
1

iex> MetamorphicLog.Keytrans.suite_id(:metamorphic_hybrid_exp)
61_440

@spec update(
  directory(),
  label_b64 :: String.t(),
  value_b64 :: String.t(),
  timestamp :: non_neg_integer(),
  opening_b64 :: String.t()
) :: {:ok, non_neg_integer()} | {:error, String.t()}

Append a new version of label with value, published at timestamp (milliseconds since the Unix epoch) and blinded by opening — the suite's Nc-byte commitment opening, which the operator supplies from a CSPRNG. Serialized against other appends.

Returns {:ok, version} with the new zero-based version number, or {:error, reason} (a wrong opening length, VRF failure, or oversized commitment inputs).

@spec verify_fixed_version(
  suite(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t()
) :: {:ok, outcome()} | {:error, String.t()}

Verify a fixed-version search proof (§7): the value bound to label at a specific version, or that that version is absent.

Returns {:ok, {:present, value_b64}}, {:ok, :absent}, or {:error, reason}.

@spec verify_monitor(
  suite(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t()
) ::
  {:ok, boolean()} | {:error, String.t()}

Verify a monitoring proof (§8): that a known (label, version) is still consistently included in the directory committed by root. A downgrade (a ladder rung that no longer proves inclusion) is rejected.

Returns {:ok, true} on success, or {:error, reason}.

@spec verify_search(
  suite(),
  String.t(),
  String.t(),
  String.t(),
  String.t(),
  String.t()
) ::
  {:ok, outcome()} | {:error, String.t()}

Verify a greatest-version search proof (§6): the value bound to label at its most recent version under the directory committed by root, or that the label is absent.

Returns {:ok, {:present, value_b64}}, {:ok, :absent}, or {:error, reason}.

Example

{:ok, {:present, value}} =
  MetamorphicLog.Keytrans.verify_search(
    :kt128_sha256_p256, context, vrf_public, root, label, proof
  )