Add preliminary harmony-crypto & harmony-identity crates

[jenglund]

Note

High Risk
Introduces new cryptographic and identity primitives (AEAD, Fernet, HKDF, key handling) where subtle correctness issues can have security implications; although largely additive, it’s security-sensitive code that will be reused broadly.

Overview
Adds a new Rust workspace (Cargo.toml, Cargo.lock) with two new crates: harmony-crypto (hashing, HKDF, Reticulum-compatible fernet token encryption, and Harmony-native ChaCha20-Poly1305 aead, plus shared CryptoError types) and harmony-identity (Ed25519/X25519 identity generation, serialization, signing/verification, and encrypt/decrypt using ephemeral ECDH + HKDF + Fernet).

Includes extensive unit tests and a reticulum_interop test suite with Python-derived vectors to validate byte-level compatibility. Also updates .gitignore to ignore Dolt .beads/* runtime files and removes those tracked artifacts.

^{Written by Cursor Bugbot for commit 5a63244. This will update automatically on new commits. Configure here.}

[jenglund]

bugbot run

[jenglund]

@greptile

[greptile-apps]

Greptile Summary

This PR introduces the harmony-crypto and harmony-identity crates, providing the core cryptographic foundation for the Harmony network stack. harmony-crypto delivers well-audited primitives (HKDF-SHA256 with RFC 5869 vectors, Reticulum-compatible Fernet AES-256-CBC + HMAC-SHA256, and ChaCha20-Poly1305 AEAD), while harmony-identity builds Ed25519/X25519 identity management with Reticulum-interoperable encrypt/decrypt and verified Python test vectors.

Overall the implementation is sound — correct encrypt-then-MAC ordering, constant-time HMAC comparison via subtle, ZeroizeOnDrop on all private-key structs, and comprehensive unit tests. However, three issues in identity.rs need attention before this is merged:

• to_private_bytes leaks key material — returns a plain [u8; 64] with no zeroization; should return Zeroizing<[u8; 64]>.
• PartialEq compares by 128-bit address hash, not the full 64-byte public key — weaker security guarantee and semantic mismatch between routing identity and cryptographic identity.
• HKDF info field is always empty — no domain separation between protocol versions or use-cases; fine for current Reticulum compatibility, but worth documenting explicitly.
• Hardcoded private key test vectors lack a "test-only, do not use in production" warning — low-severity risk but important to guard against accidental production reuse.

Confidence Score: 2/5

• Not safe to merge until to_private_bytes is hardened and PartialEq is corrected — both are security-sensitive in a cryptographic identity crate.
• The primitive crates (harmony-crypto) are solid and well-tested. The identity crate has two logic-level security issues: private key material is returned without automatic zeroization, and identity equality is based only on a 128-bit truncated hash rather than the full public key. Either issue could be exploited in downstream code that trusts this API. The test file also commits real private key bytes without a warning, which is a reuse risk. Fixing these issues is straightforward and the overall cryptographic design is sound.
• Pay close attention to crates/harmony-identity/src/identity.rs — all three flagged issues are concentrated there.

Important Files Changed

Filename	Overview
crates/harmony-identity/src/identity.rs	Core identity module with three issues: to_private_bytes returns unprotected key material (no ZeroizeOnDrop), PartialEq compares only the 128-bit truncated address hash instead of the full 64-byte public key, and HKDF derivation uses empty info with no domain separation.
crates/harmony-crypto/src/fernet.rs	Well-structured Reticulum-compatible Fernet (AES-256-CBC + HMAC-SHA256) with correct encrypt-then-MAC ordering, constant-time HMAC verification via subtle::ConstantTimeEq, and proper minimum-length checks. Key material is passed in and out via caller-owned slices with FernetKey providing zeroization.
crates/harmony-crypto/src/aead.rs	ChaCha20-Poly1305 AEAD wrapper with comprehensive nonce-reuse documentation. AeadKey zeroizes on drop. from_bytes accepts value by move, so the caller must manually zeroize their source array — minor but worth noting.
crates/harmony-crypto/src/hkdf.rs	HKDF-SHA256 wrapper with RFC 5869 test vectors, DerivedKey zeroizing wrapper, and explicit bounds checking. Clean and correct implementation.
crates/harmony-identity/tests/reticulum_interop.rs	Solid interop test suite with Reticulum Python vectors covering address derivation, signing, and decryption. Four hardcoded private keys committed to source without a "test-only" warning — risks accidental production reuse.

Sequence Diagram

sequenceDiagram
    participant Sender
    participant Identity
    participant HKDF
    participant Fernet

    Note over Sender,Fernet: Identity encrypt (Reticulum-compatible)
    Sender->>Identity: encrypt(rng, plaintext)
    Identity->>Identity: generate ephemeral X25519 keypair
    Identity->>Identity: X25519 ECDH → shared secret
    Identity->>HKDF: derive_key_256(shared_secret, salt=address_hash)
    HKDF-->>Identity: 64-byte Fernet key
    Identity->>Fernet: encrypt(rng, fernet_key, plaintext)
    Fernet->>Fernet: random IV (16 bytes)
    Fernet->>Fernet: AES-256-CBC encrypt (PKCS7)
    Fernet->>Fernet: HMAC-SHA256 over IV + ciphertext
    Fernet-->>Identity: token = IV + ciphertext + HMAC
    Identity->>Identity: zeroize fernet_key
    Identity-->>Sender: ephemeral_pub (32B) + token

    Note over Sender,Fernet: PrivateIdentity decrypt
    Sender->>Identity: decrypt(ciphertext)
    Identity->>Identity: extract ephemeral_pub (first 32 bytes)
    Identity->>Identity: X25519 ECDH → shared secret
    Identity->>HKDF: derive_key_256(shared_secret, salt=address_hash)
    HKDF-->>Identity: 64-byte Fernet key
    Identity->>Fernet: decrypt(fernet_key, token)
    Fernet->>Fernet: constant-time HMAC verify
    Fernet->>Fernet: AES-256-CBC decrypt + unpad
    Fernet-->>Identity: plaintext
    Identity->>Identity: zeroize fernet_key
    Identity-->>Sender: plaintext

Loading

_{Last reviewed commit: 5a63244}

[greptile-apps]

_{18 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[jenglund]

bugbot run
@greptile

[greptile-apps]

minimum ciphertext check should be 96 bytes (32-byte ephemeral key + 64-byte minimum Fernet token), not 33

Suggested change

	if ciphertext.len() < 33 {
	return Err(IdentityError::DecryptionFailed);
	}
	if ciphertext.len() < 96 {
	return Err(IdentityError::DecryptionFailed);
	}

[greptile-apps]

add documentation warning that nonce MUST NEVER be reused with the same key in ChaCha20-Poly1305, as reuse completely breaks security

[jenglund]

bugbot run
@greptile

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

[jenglund]

As much as I could run tests/reviews one more time to be extra sure, I'm excited to move on, there's a lot more to build out! SO MERGING CHOO CHOO HERE WE GO

[jenglund]

bugbot run

[cursor]

Identity equality ignores actual cryptographic key material

Low Severity

The PartialEq impl for Identity compares only the 16-byte address_hash, not the actual encryption_key or verifying_key. This means two Identity values with different public keys but a colliding truncated hash would be considered equal, even though they behave differently for verify() and encrypt(). Comparing the full 64-byte public key material would be equally efficient and semantically correct, avoiding a potential foot-gun where code assumes a == b implies cryptographic interchangeability.

 

[jenglund]

bugbot run

[jenglund]

@greptile

[greptile-apps]

to_private_bytes returns unprotected key material

to_private_bytes returns a plain [u8; 64] containing raw private key bytes. Unlike PrivateIdentity itself (which is ZeroizeOnDrop), the returned array carries no automatic zeroization guarantee. Any caller that stores the returned bytes, passes them to another function, or simply lets the binding go out of scope without explicitly calling zeroize() will leave live private key material on the stack/heap until it is overwritten by unrelated data.

The function should return a zeroizing wrapper (e.g., zeroize::Zeroizing<[u8; PRIVATE_KEY_LENGTH]>) so that the secret bytes are automatically erased when the returned value is dropped:

use zeroize::Zeroizing;

pub fn to_private_bytes(&self) -> Zeroizing<[u8; PRIVATE_KEY_LENGTH]> {
    let mut bytes = Zeroizing::new([0u8; PRIVATE_KEY_LENGTH]);
    bytes[..32].copy_from_slice(self.encryption_secret.as_bytes());
    bytes[32..].copy_from_slice(self.signing_key.as_bytes());
    bytes
}

Zeroizing<T> implements Deref<Target = T>, so callers that read the bytes via as_slice() or indexing continue to work without change, while the secret material is guaranteed to be wiped on drop.

[greptile-apps]

PartialEq uses truncated 128-bit hash instead of full public key

The PartialEq implementation compares identities only by address_hash, which is a 16-byte (128-bit) truncation of SHA-256. This is weaker than comparing the full 64-byte public key for two reasons:

1. Cryptographic strength: A birthday collision in 128-bit space requires roughly 2^64 attempts — feasible for a nation-state-level adversary targeting a specific identity. If equality is used in any security-sensitive context (access control, trust checks, deduplication of allowed peers), a crafted identity that collides in the address hash would pass these checks despite having different — and attacker-controlled — public keys.

2. Semantic mismatch: The address hash is a routing address (Reticulum's network-layer notion of location); cryptographic identity equality should be based on the actual public key material. Using address hashes for equality silently conflates two different concepts, which can confuse future users of the API.

The comparison should use the full combined public key bytes:

impl PartialEq for Identity {
    fn eq(&self, other: &Self) -> bool {
        self.to_public_bytes() == other.to_public_bytes()
    }
}

impl Eq for Identity {}

If two Identity values are equal under this definition, their address_hash fields will also match (since the hash is derived deterministically from the keys). The converse is not guaranteed.

[greptile-apps]

Missing HKDF info context — no domain separation

derive_key_256 is called with an empty info slice (&[] is the default in the implementation). The HKDF info parameter is the standard mechanism for domain separation: it binds the derived key to a specific protocol, version, and usage. Without it, any other code that performs an ECDH exchange over the same X25519 keys and then applies HKDF-SHA256 with the same salt would derive the identical Fernet key, even if that code is meant for a completely different purpose.

Consider adding a well-known, constant context string:

let mut derived = hkdf::derive_key_256(
    shared_secret.as_bytes(),
    Some(&self.address_hash),
    b"harmony-identity-v1-fernet",  // add an info parameter to derive_key_256
);

Note: if Reticulum Python uses empty info, and the interoperability test vectors rely on that, changing the info would break wire compatibility. In that case, keep the empty info but document this explicitly so that future protocol versions (with a different info string) remain clearly separated. The same pattern applies to the decrypt path at line 202.

[greptile-apps]

Hardcoded private key bytes in source — add prominent "test-only" warning

vectors::X25519_PRIVATE, vectors::ED25519_PRIVATE, vectors::ID2_X25519_PRIVATE, and vectors::ID2_ED25519_PRIVATE are real X25519 and Ed25519 private keys committed to the repository. Anyone who can read this file now possesses those private keys. If these values are ever accidentally used in a production deployment (e.g., as "default" seed keys, for smoke-testing against a live node, or via copy-paste), all traffic encrypted to those identities would be trivially decryptable.

Add a clear comment block at the top of the vectors module:

/// ⚠ WARNING: These are TEST-ONLY private keys.
/// They are committed to a public repository and MUST NEVER be used
/// outside of unit/integration tests. Any identity or data protected
/// by these keys should be considered fully compromised.
mod vectors {

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Derived key not zeroized on error path in encrypt

Low Severity

In Identity::encrypt, the ? operator on the fernet::encrypt call causes an early return that skips derived.zeroize(), leaving 64 bytes of derived key material on the stack. The sibling PrivateIdentity::decrypt method correctly avoids this by capturing the result into a variable, calling derived.zeroize(), and only then returning — the encrypt path is inconsistent with this safer pattern.

Additional Locations (1)

• crates/harmony-identity/src/identity.rs#L206-L214