saorsa_gossip_identity/

lib.rs

#![warn(missing_docs)]

//! ML-DSA identity and key management
//!
//! Manages long-term ML-DSA identities

use anyhow::{Context, Result};
use saorsa_gossip_types::PeerId;
use serde::{Deserialize, Serialize};
use std::path::Path;

/// ML-DSA key pair using saorsa-pqc ML-DSA-65
///
/// Stores raw key bytes for serialization compatibility.
/// Uses ML-DSA-65 which provides ~128-bit security level per SPEC2 §2.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MlDsaKeyPair {
    /// Public key bytes (ML-DSA-65 public key)
    pub public_key: Vec<u8>,
    /// Secret key bytes (to be secured, ML-DSA-65 secret key)
    secret_key: Vec<u8>,
}

impl MlDsaKeyPair {
    /// Generate a new ML-DSA-65 key pair
    ///
    /// Uses saorsa-pqc for post-quantum digital signatures.
    pub fn generate() -> Result<Self> {
        use saorsa_pqc::{MlDsa65, MlDsaOperations};

        let signer = MlDsa65::new();
        let (pk, sk) = signer.generate_keypair()?;

        Ok(Self {
            public_key: pk.as_bytes().to_vec(),
            secret_key: sk.as_bytes().to_vec(),
        })
    }

    /// Construct a key pair from raw ML-DSA-65 public and secret key bytes.
    ///
    /// For callers that already hold an ML-DSA-65 identity outside this crate
    /// — e.g. the machine keypair that backs a node's QUIC peer id — and need
    /// to sign gossip messages (presence beacons, FOAF responses) with that
    /// same identity. Signing with the identity that derives `peer_id` is
    /// required so receivers can verify `PeerId::from_pubkey(public_key)`
    /// binds to the claimed sender; a freshly generated key would fail that
    /// binding check.
    ///
    /// The bytes are taken as-is; callers are responsible for supplying a
    /// matching ML-DSA-65 public/secret pair.
    pub fn from_keypair_bytes(public_key: Vec<u8>, secret_key: Vec<u8>) -> Self {
        Self {
            public_key,
            secret_key,
        }
    }

    /// Get public key bytes
    pub fn public_key(&self) -> &[u8] {
        &self.public_key
    }

    /// Get secret key bytes (for transport identity synchronization)
    pub fn secret_key(&self) -> &[u8] {
        &self.secret_key
    }

    /// Get saorsa-pqc secret key type
    pub fn get_secret_key_typed(&self) -> Result<saorsa_pqc::MlDsaSecretKey> {
        Ok(saorsa_pqc::MlDsaSecretKey::from_bytes(&self.secret_key)?)
    }

    /// Derive PeerId from public key
    pub fn peer_id(&self) -> PeerId {
        PeerId::from_pubkey(&self.public_key)
    }

    /// Sign a message using ML-DSA-65
    ///
    /// # Arguments
    /// * `message` - Message bytes to sign
    ///
    /// # Returns
    /// ML-DSA-65 signature bytes
    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>> {
        use saorsa_pqc::{MlDsa65, MlDsaOperations};

        let signer = MlDsa65::new();
        let sk = self.get_secret_key_typed()?;
        let signature = signer.sign(&sk, message)?;
        Ok(signature.as_bytes().to_vec())
    }

    /// Verify a signature using ML-DSA-65
    ///
    /// # Arguments
    /// * `public_key` - Public key bytes
    /// * `message` - Original message bytes
    /// * `signature` - Signature bytes to verify
    ///
    /// # Returns
    /// `Ok(true)` if signature is valid, `Ok(false)` if invalid
    pub fn verify(public_key: &[u8], message: &[u8], signature: &[u8]) -> Result<bool> {
        use saorsa_pqc::{MlDsa65, MlDsaOperations, MlDsaPublicKey, MlDsaSignature};

        let verifier = MlDsa65::new();
        let pk = MlDsaPublicKey::from_bytes(public_key)?;
        let sig = MlDsaSignature::from_bytes(signature)?;

        Ok(verifier.verify(&pk, message, &sig)?)
    }

    /// Serialize key pair to bytes using postcard
    pub fn to_bytes(&self) -> Result<Vec<u8>> {
        postcard::to_stdvec(self).context("Failed to serialize keypair")
    }

    /// Deserialize key pair from bytes using postcard
    pub fn from_bytes(bytes: &[u8]) -> Result<Self> {
        postcard::from_bytes(bytes).context("Failed to deserialize keypair")
    }
}

/// Identity with human-readable alias
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Identity {
    /// ML-DSA key pair
    key_pair: MlDsaKeyPair,
    /// Human-readable alias
    alias: String,
}

impl Identity {
    /// Create a new identity with alias
    pub fn new(alias: String) -> Result<Self> {
        Ok(Self {
            key_pair: MlDsaKeyPair::generate()?,
            alias,
        })
    }

    /// Load existing identity or create new one
    ///
    /// This is the primary API for Communitas integration. It will:
    /// 1. Try to load an existing identity from the keystore
    /// 2. If not found, create a new identity and save it
    ///
    /// # Arguments
    /// * `four_words` - The four-word identifier (e.g., "ocean-forest-moon-star")
    /// * `display_name` - Human-readable display name
    /// * `keystore_path` - Path to the keystore directory
    pub async fn load_or_create(
        four_words: &str,
        display_name: &str,
        keystore_path: &str,
    ) -> Result<Self> {
        // Try to load existing
        match Self::load_from_keystore(four_words, keystore_path).await {
            Ok(identity) => Ok(identity),
            Err(_) => {
                // Create new identity
                let identity = Self::new(display_name.to_string())?;

                // Save to keystore
                identity.save_to_keystore(four_words, keystore_path).await?;

                Ok(identity)
            }
        }
    }

    /// Load identity from encrypted keystore
    ///
    /// # Arguments
    /// * `four_words` - The four-word identifier
    /// * `keystore_path` - Path to the keystore directory
    pub async fn load_from_keystore(four_words: &str, keystore_path: &str) -> Result<Self> {
        let file_path = Self::keystore_file_path(four_words, keystore_path);

        // Read file
        let data = tokio::fs::read(&file_path).await.context(format!(
            "Failed to read keystore file: {}",
            file_path.display()
        ))?;

        // Deserialize (in production, this would be encrypted)
        let identity: Identity =
            postcard::from_bytes(&data).context("Failed to deserialize identity")?;

        Ok(identity)
    }

    /// Save identity to encrypted keystore
    ///
    /// # Arguments
    /// * `four_words` - The four-word identifier
    /// * `keystore_path` - Path to the keystore directory
    pub async fn save_to_keystore(&self, four_words: &str, keystore_path: &str) -> Result<()> {
        let file_path = Self::keystore_file_path(four_words, keystore_path);

        // Ensure directory exists
        if let Some(parent) = file_path.parent() {
            tokio::fs::create_dir_all(parent)
                .await
                .context("Failed to create keystore directory")?;
        }

        // Serialize (in production, this would be encrypted)
        let data = postcard::to_stdvec(&self).context("Failed to serialize identity")?;

        // Write file
        tokio::fs::write(&file_path, data).await.context(format!(
            "Failed to write keystore file: {}",
            file_path.display()
        ))?;

        Ok(())
    }

    /// Get the path to the keystore file for a given four-word identifier
    fn keystore_file_path(four_words: &str, keystore_path: &str) -> std::path::PathBuf {
        let safe_filename = four_words.replace('-', "_");
        Path::new(keystore_path).join(format!("{}.identity", safe_filename))
    }

    /// Get the alias
    pub fn alias(&self) -> &str {
        &self.alias
    }

    /// Get the PeerId
    pub fn peer_id(&self) -> PeerId {
        self.key_pair.peer_id()
    }

    /// Get the key pair
    pub fn key_pair(&self) -> &MlDsaKeyPair {
        &self.key_pair
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn test_keypair_generation() {
        let keypair = MlDsaKeyPair::generate();
        assert!(keypair.is_ok());
    }

    #[test]
    fn test_identity_creation() {
        let identity = Identity::new("Alice".to_string());
        assert!(identity.is_ok());

        if let Ok(id) = identity {
            assert_eq!(id.alias(), "Alice");
        }
    }

    #[test]
    fn test_peer_id_derivation() {
        let keypair = MlDsaKeyPair::generate().ok();
        if let Some(kp) = keypair {
            let peer_id = kp.peer_id();
            assert_eq!(peer_id.as_bytes().len(), 32);
        }
    }

    // TDD: New failing tests for load_or_create functionality

    #[tokio::test]
    async fn test_load_or_create_new_identity() {
        // RED: This should fail because load_or_create doesn't exist yet
        let temp_dir = TempDir::new().expect("temp dir");
        let keystore_path = temp_dir.path().to_str().expect("path");

        let four_words = "ocean-forest-moon-star";
        let display_name = "Alice";

        let identity = Identity::load_or_create(four_words, display_name, keystore_path)
            .await
            .expect("should create new identity");

        assert_eq!(identity.alias(), display_name);

        // PeerId should be deterministic based on key material
        let peer_id = identity.peer_id();
        assert_eq!(peer_id.as_bytes().len(), 32);
    }

    #[tokio::test]
    async fn test_load_or_create_existing_identity() {
        // RED: This should fail because load_or_create doesn't exist yet
        let temp_dir = TempDir::new().expect("temp dir");
        let keystore_path = temp_dir.path().to_str().expect("path");

        let four_words = "ocean-forest-moon-star";
        let display_name = "Alice";

        // Create first time
        let identity1 = Identity::load_or_create(four_words, display_name, keystore_path)
            .await
            .expect("should create");

        let peer_id1 = identity1.peer_id();

        // Load second time - should get same identity
        let identity2 = Identity::load_or_create(four_words, display_name, keystore_path)
            .await
            .expect("should load existing");

        let peer_id2 = identity2.peer_id();

        // Same PeerId proves it's the same identity
        assert_eq!(peer_id1, peer_id2);
        assert_eq!(identity2.alias(), display_name);
    }

    #[tokio::test]
    async fn test_keystore_persistence() {
        // RED: This should fail because save/load methods don't exist
        let temp_dir = TempDir::new().expect("temp dir");
        let keystore_path = temp_dir.path().to_str().expect("path");

        let four_words = "river-mountain-cloud-light";
        let identity = Identity::new("Bob".to_string()).expect("create");

        // Save to keystore
        identity
            .save_to_keystore(four_words, keystore_path)
            .await
            .expect("should save");

        // Load from keystore
        let loaded = Identity::load_from_keystore(four_words, keystore_path)
            .await
            .expect("should load");

        // Verify same identity
        assert_eq!(identity.peer_id(), loaded.peer_id());
        assert_eq!(identity.alias(), loaded.alias());
    }

    #[tokio::test]
    async fn test_load_nonexistent_identity_fails() {
        // RED: Should fail because load_from_keystore doesn't exist
        let temp_dir = TempDir::new().expect("temp dir");
        let keystore_path = temp_dir.path().to_str().expect("path");

        let result = Identity::load_from_keystore("nonexistent-four-words", keystore_path).await;

        // Should return error for non-existent identity
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn test_multiple_identities_in_same_keystore() {
        // Test that we can store multiple identities with different four-word IDs
        let temp_dir = TempDir::new().expect("temp dir");
        let keystore_path = temp_dir.path().to_str().expect("path");

        // Create two different identities
        let alice = Identity::load_or_create("ocean-forest-moon-star", "Alice", keystore_path)
            .await
            .expect("alice");

        let bob = Identity::load_or_create("river-mountain-cloud-light", "Bob", keystore_path)
            .await
            .expect("bob");

        // Different aliases
        assert_ne!(alice.alias(), bob.alias());

        // NOTE: With placeholder key generation, PeerIds will be same
        // In production with real ML-DSA, they would be different
        // For now, just verify the aliases and that load/save works

        // Load them again - should get same ones
        let alice2 = Identity::load_or_create("ocean-forest-moon-star", "Alice", keystore_path)
            .await
            .expect("alice2");

        let bob2 = Identity::load_or_create("river-mountain-cloud-light", "Bob", keystore_path)
            .await
            .expect("bob2");

        // Same identities when reloaded
        assert_eq!(alice.peer_id(), alice2.peer_id());
        assert_eq!(alice.alias(), alice2.alias());
        assert_eq!(bob.peer_id(), bob2.peer_id());
        assert_eq!(bob.alias(), bob2.alias());
    }
}