@spec parse(body_text :: String.t()) :: {:ok, t()} | {:error, String.t()}

Parse an unverified checkpoint body (no signature check).

Use this only when the signature has already been established out of band; otherwise prefer verify/2. Returns {:ok, %Checkpoint{}} or {:error, reason}.

@spec sign_hybrid(
  origin :: String.t(),
  size :: non_neg_integer(),
  root_b64 :: String.t(),
  name :: String.t(),
  secret_key_b64 :: String.t()
) :: {:ok, String.t()} | {:error, String.t()}

Build a checkpoint body and sign it with a hybrid PQ composite secret key in one call, returning the complete C2SP signed-note text ready to publish.

origin is the log identity line; size the tree size; root_b64 the base64 of the exactly 32-byte RFC 6962 root at size; name the C2SP key name (usually the origin); secret_key_b64 the base64 composite secret key.

This is the one-call producer path for a checkpoint publisher: it shares the core's Checkpoint + sign_hybrid code path, so it never hand-assembles the byte layout. The verifier key derived from secret_key_b64's public half (MetamorphicLog.VerifierKey.encode_hybrid/2) verifies the produced note via verify/2.

Returns {:ok, note_text} or {:error, reason} (malformed checkpoint — empty origin or non-32-byte root — or a signing failure).

Example

{:ok, note} =
  MetamorphicLog.Checkpoint.sign_hybrid("origin/log", 10, root_b64, "origin/log", sk)

@spec verify(note_text :: String.t(), trusted_vkeys :: [String.t()]) ::
  {:ok, t()} | {:error, String.t()}

Verify a signed-note note_text against trusted_vkeys and return the enclosed checkpoint.

Returns {:ok, %Checkpoint{}} or {:error, reason}.

Example

{:ok, %MetamorphicLog.Checkpoint{size: size, root: root}} =
  MetamorphicLog.Checkpoint.verify(note_text, [vkey])

@spec verify_consistency(
  older_note :: String.t(),
  newer_note :: String.t(),
  trusted_vkeys :: [String.t()],
  proof_b64 :: [String.t()]
) :: :ok | {:error, String.t()}

Verify both older_note and newer_note against trusted_vkeys, then verify that the newer checkpoint is a consistent extension of the older one.

proof is a list of base64-encoded hashes. Returns :ok or {:error, reason}.

@spec verify_inclusion(
  note_text :: String.t(),
  trusted_vkeys :: [String.t()],
  leaf_index :: non_neg_integer(),
  leaf_hash_b64 :: String.t(),
  proof_b64 :: [String.t()]
) :: :ok | {:error, String.t()}

Verify note_text against trusted_vkeys, then verify that leaf_hash is included at leaf_index under that checkpoint's root.

proof is a list of base64-encoded sibling hashes. Returns :ok or {:error, reason}.