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

Re-derive the base64 public_key from a base64 hybrid secret_key.

Both component public keys are a deterministic function of the secret seeds, so this reproduces exactly the public_key returned by generate_signing_keypair/1. Useful for recovering a public key from a backed-up secret, or for checking that a secret/public pair belong together. The security level is read from the secret key's wire tag.

Returns {:ok, public_key_b64} or {:error, reason} (invalid base64, wrong length, or unknown version tag).

Example

kp = MetamorphicCrypto.Sign.generate_signing_keypair()
{:ok, pk} = MetamorphicCrypto.Sign.derive_public_key(kp.secret_key)
# pk == kp.public_key

@spec derive_public_key!(secret_key_b64 :: String.t()) :: String.t()

Same as derive_public_key/1 but returns the public key directly, raising on invalid input.

@spec generate_signing_keypair(level()) :: keypair()

Generate a hybrid signing keypair at the given security level (default :cat3).

Returns a map %{public_key: base64, secret_key: base64} using the documented byte layout. The two component algorithms are seeded from independent OS randomness.

Examples

kp = MetamorphicCrypto.Sign.generate_signing_keypair()
kp = MetamorphicCrypto.Sign.generate_signing_keypair(:cat5)

@spec generate_signing_keypair_suite(suite(), level()) ::
  {:ok, keypair()} | {:error, String.t()}

Generate a hybrid signing keypair for the given suite/0 + level/0 (default :cat5).

:hybrid (any level) and :hybrid_matched at :cat2 produce the existing ML-DSA + Ed25519 keys (byte-identical to generate_signing_keypair/1). The matched Cat-3/Cat-5 and pure suites produce the new combined-key layouts. sign/3 / verify/4 / derive_public_key/1 need no suite argument — they read it from the wire tag.

Returns {:ok, %{public_key: base64, secret_key: base64}}, or {:error, reason} for unsupported combinations (e.g. :pure_cnsa2 below :cat5).

Examples

# Pure CNSA 2.0 (ML-DSA-87, Cat-5 only)
{:ok, kp} = MetamorphicCrypto.Sign.generate_signing_keypair_suite(:pure_cnsa2, :cat5)

# Matched-strength hybrid (ML-DSA-65 + Ed448)
{:ok, kp} = MetamorphicCrypto.Sign.generate_signing_keypair_suite(:hybrid_matched, :cat3)

@spec sign(message :: binary(), context :: String.t(), secret_key_b64 :: String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

Sign message under context with a base64 hybrid secret_key.

message is a raw binary, context is a UTF-8 label (use sign_context_v1/0 or another versioned string), and secret_key is base64. Produces a composite signature — a hedged (randomized) ML-DSA signature and a deterministic Ed25519 signature, both over the domain-separated frame(context, message). The security level is read from the secret key's wire tag.

Returns {:ok, signature_b64} or {:error, reason}. Because ML-DSA signing is randomized, signing the same message twice yields different (both-valid) signatures — never pin the signature bytes.

Example

kp = MetamorphicCrypto.Sign.generate_signing_keypair()
{:ok, sig} =
  MetamorphicCrypto.Sign.sign("log entry", MetamorphicCrypto.Sign.sign_context_v1(), kp.secret_key)

@spec sign!(message :: binary(), context :: String.t(), secret_key_b64 :: String.t()) ::
  String.t()

Same as sign/3 but returns the signature directly, raising on invalid input.

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

The recommended versioned context label for general-purpose signing: "metamorphic/sign/v1".

Pass this (or another versioned "namespace/purpose/vN" label) as the context argument to sign/3 / verify/4 to bind signatures to a purpose.

Example

iex> MetamorphicCrypto.Sign.sign_context_v1()
"metamorphic/sign/v1"

@spec signature_posture(public_key_b64 :: String.t()) ::
  {:ok, {suite(), level()}} | {:error, String.t()}

Report the {suite, level} posture declared by a base64 signing public key, without exposing the raw wire tag.

Composite artifacts produced by this package are self-describing: their leading version tag encodes which suite/0 and level/0 produced them. This is the typed, opaque decode of that contract — it lets a verifier learn the posture of a key it was handed and check it against an independently declared expectation (a "declared == observed" check), without re-deriving the private wire tags itself.

The full decoded blob length is validated against the expected length for the decoded posture (mirroring verify/4's length checks), so a truncated, over-long, or otherwise malformed key is rejected with {:error, reason} rather than silently misreporting a posture. An unknown/missing tag or invalid base64 is likewise {:error, reason}.

Returns {:ok, {suite, level}} or {:error, reason}.

Cat-2 aliasing

:hybrid and :hybrid_matched are byte-identical at :cat2 (both tag 0x01), so a Cat-2 key canonically decodes to {:hybrid, :cat2}.

Example

{:ok, kp} = MetamorphicCrypto.Sign.generate_signing_keypair_suite(:pure_cnsa2, :cat5)
{:ok, {:pure_cnsa2, :cat5}} = MetamorphicCrypto.Sign.signature_posture(kp.public_key)

@spec signature_posture_from_signature(signature_b64 :: String.t()) ::
  {:ok, {suite(), level()}} | {:error, String.t()}

Report the {suite, level} posture declared by a base64 composite signature, without exposing the raw wire tag.

The signature counterpart to signature_posture/1; see that function for the self-describing-artifact contract, the Cat-2 aliasing note ({:hybrid, :cat2}), and the honest framing (declared posture, not a verification result). The full decoded length is validated against the expected signature length for the decoded posture, so a truncated/garbage/wrong-length signature is {:error, reason} rather than misreported.

Returns {:ok, {suite, level}} or {:error, reason}.

Example

kp = MetamorphicCrypto.Sign.generate_signing_keypair(:cat3)
{:ok, sig} = MetamorphicCrypto.Sign.sign("checkpoint", MetamorphicCrypto.Sign.sign_context_v1(), kp.secret_key)
{:ok, {:hybrid, :cat3}} = MetamorphicCrypto.Sign.signature_posture_from_signature(sig)

@spec verify(
  message :: binary(),
  context :: String.t(),
  signature_b64 :: String.t(),
  public_key_b64 :: String.t()
) :: boolean()

Verify a composite signature over message / context against public_key.

message is a raw binary, context is the UTF-8 label used at signing time, and signature / public_key are base64. Returns true only if both the Ed25519 and ML-DSA component signatures verify (strict AND).

Returns false for any verification failure — a tampered message/context, a wrong key, a tampered half-signature, a cross-level or stripped artifact, or a malformed input (invalid base64 / unknown version tag). The function never raises and never returns an error tuple: a non-true result always means "not a valid signature", which is the safe default for a verifier.

Example

kp = MetamorphicCrypto.Sign.generate_signing_keypair()
{:ok, sig} = MetamorphicCrypto.Sign.sign("msg", "metamorphic/sign/v1", kp.secret_key)
true = MetamorphicCrypto.Sign.verify("msg", "metamorphic/sign/v1", sig, kp.public_key)