synor/crates/synor-crypto/src/lib.rs

//! Quantum-resistant cryptography for the Synor blockchain.
//!
//! This crate provides hybrid cryptographic primitives combining:
//! - **Ed25519**: Fast, battle-tested elliptic curve signatures
//! - **Dilithium3 (ML-DSA-65)**: NIST post-quantum digital signatures
//! - **Kyber768 (ML-KEM-768)**: NIST post-quantum key encapsulation
//!
//! # Why Hybrid Cryptography?
//!
//! The hybrid approach ensures security against both classical and quantum attacks.
//! An attacker would need to break BOTH algorithms to compromise the system.
//!
//! | Algorithm | Type | Security Level | Key Size | Sig Size |
//! |-----------|------|----------------|----------|----------|
//! | Ed25519 | Classical | 128-bit | 32 bytes | 64 bytes |
//! | Dilithium3 | Post-quantum | 192-bit | 1,952 bytes | 3,293 bytes |
//! | **Hybrid** | Both | 192-bit | ~2KB | ~3.4KB |
//!
//! # Quick Start
//!
//! ## Generate a Wallet
//!
//! ```rust
//! use synor_crypto::{Mnemonic, HybridKeypair, Network};
//!
//! // Generate a 24-word mnemonic (256-bit entropy)
//! let mnemonic = Mnemonic::generate(24).unwrap();
//! println!("Backup these words: {}", mnemonic.phrase());
//!
//! // Derive keypair from mnemonic
//! let keypair = HybridKeypair::from_mnemonic(&mnemonic, "").unwrap();
//!
//! // Get your address
//! let address = keypair.address(Network::Mainnet);
//! println!("Your address: {}", address);
//! ```
//!
//! ## Sign and Verify Messages
//!
//! ```rust
//! use synor_crypto::{HybridKeypair, Mnemonic};
//!
//! let mnemonic = Mnemonic::generate(24).unwrap();
//! let keypair = HybridKeypair::from_mnemonic(&mnemonic, "").unwrap();
//!
//! // Sign a message
//! let message = b"Hello, Synor!";
//! let signature = keypair.sign(message);
//!
//! // Verify the signature
//! assert!(keypair.public_key().verify(message, &signature).is_ok());
//!
//! // Signature is ~3.4KB (Ed25519 + Dilithium3)
//! println!("Signature size: {} bytes", signature.to_bytes().len());
//! ```
//!
//! ## Recover from Mnemonic
//!
//! ```rust
//! use synor_crypto::{Mnemonic, HybridKeypair, Network};
//!
//! // User provides their backup phrase
//! let phrase = "abandon abandon abandon abandon abandon abandon abandon abandon \
//!               abandon abandon abandon abandon abandon abandon abandon abandon \
//!               abandon abandon abandon abandon abandon abandon abandon art";
//!
//! let mnemonic = Mnemonic::from_phrase(phrase).unwrap();
//! let keypair = HybridKeypair::from_mnemonic(&mnemonic, "").unwrap();
//!
//! // Same mnemonic always produces the same keypair
//! let address = keypair.address(Network::Mainnet);
//! ```
//!
//! # Security Considerations
//!
//! 1. **Mnemonic Storage**: Never store mnemonics in plaintext. Use secure storage.
//! 2. **Password Protection**: Use a strong passphrase with `from_mnemonic(..., passphrase)`.
//! 3. **Key Derivation**: Keys are derived using Argon2id with high memory cost.
//! 4. **Hybrid Verification**: Both Ed25519 AND Dilithium3 signatures must be valid.
//!
//! # Performance
//!
//! Typical operations on modern hardware:
//! - Key generation: ~1ms
//! - Signing: ~150µs
//! - Verification: ~85µs (hybrid)

#![allow(dead_code)]

pub mod falcon;
pub mod kdf;
pub mod keypair;
pub mod mnemonic;
pub mod negotiation;
pub mod signature;
pub mod sphincs;

pub use kdf::{derive_key, DeriveKeyError};
pub use keypair::{Ed25519Keypair, HybridKeypair, PublicKey, SecretKey};
pub use mnemonic::{Mnemonic, MnemonicError};
pub use signature::{HybridSignature, Signature, SignatureError};

// FIPS 205 (SLH-DSA) - Hash-based backup signatures
pub use sphincs::{
    SphincsError, SphincsKeypair, SphincsPublicKey, SphincsSecretKey, SphincsSignature,
    SphincsVariant,
};

// FIPS 206 (FN-DSA) - Compact lattice signatures
pub use falcon::{
    FalconError, FalconKeypair, FalconPublicKey, FalconSecretKey, FalconSignature, FalconVariant,
};

// Algorithm negotiation protocol
pub use negotiation::{
    AlgorithmCapabilities, AlgorithmFamily, AlgorithmNegotiator, NegotiationError,
    NegotiationMessage, NegotiationPolicy, NegotiationResult, PqAlgorithm, ScoringStrategy,
    SessionParams,
};

/// Re-export common types
pub use synor_types::{Address, Hash256, Network};

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_full_workflow() {
        // Generate mnemonic
        let mnemonic = Mnemonic::generate(24).unwrap();
        println!("Mnemonic: {}", mnemonic.phrase());

        // Derive keypair from mnemonic
        let keypair = HybridKeypair::from_mnemonic(&mnemonic, "").unwrap();

        // Get address
        let address = keypair.address(Network::Mainnet);
        println!("Address: {}", address);

        // Sign a message
        let message = b"Hello, Synor!";
        let signature = keypair.sign(message);

        // Verify signature
        assert!(keypair.public_key().verify(message, &signature).is_ok());
    }
}