feat: Add examples and an easy API, refactor documentation structure, and update core message protocol.

Author: NotUnHackable

EXPLANATION/NotebookLM.png EXPLANATION/FlowChart.pngEXPLANATION/NotebookLM.png renamed to EXPLANATION/FlowChart.png

@@ -0,0 +1,70 @@
+//! Basic LMP Usage Example
+//!
+//! This example demonstrates how to:
+//! 1. Create an LMP client
+//! 2. Generate an introduction token
+//! 3. Establish a session between two parties
+//!
+//! Run with: cargo run --example basic_usage
+
+use lmp_core::prelude::*;
+
+fn main() -> Result<()> {
+    println!("=== LMP Basic Usage Example ===\n");
+
+    // Step 1: Create two clients (Alice and Bob)
+    println!("Creating clients...");
+    let alice = LmpClient::new()?;
+    let bob = LmpClient::new()?;
+
+    println!("  Alice's device ID: {}", hex::encode(alice.device_id()));
+    println!("  Bob's device ID:   {}", hex::encode(bob.device_id()));
+    println!();
+
+    // Step 2: Get fingerprints for verification
+    println!("Identity fingerprints (for out-of-band verification):");
+    println!("  Alice: {}", alice.fingerprint());
+    println!("  Bob:   {}", bob.fingerprint());
+    println!();
+
+    // Step 3: Create introduction tokens
+    println!("Creating introduction tokens...");
+    let alice_token = alice.get_introduction_token("dht://alice.example.com:4001")?;
+    let bob_token = bob.get_introduction_token("dht://bob.example.com:4001")?;
+
+    // Verify tokens
+    alice_token.verify()?;
+    bob_token.verify()?;
+    println!("  ✓ Both tokens verified");
+    println!();
+
+    // Step 4: Serialize tokens for sharing
+    println!("Token sharing (base64 format):");
+    let alice_b64 = alice_token.to_base64()?;
+    let bob_b64 = bob_token.to_base64()?;
+    
+    println!("  Alice's token: {}...{}", &alice_b64[..20], &alice_b64[alice_b64.len()-10..]);
+    println!("  Bob's token:   {}...{}", &bob_b64[..20], &bob_b64[bob_b64.len()-10..]);
+    println!();
+
+    // Step 5: Show token fingerprints for quick verification
+    println!("Token fingerprints:");
+    println!("  Alice: {}", alice_token.fingerprint());
+    println!("  Bob:   {}", bob_token.fingerprint());
+    println!();
+
+    // Step 6: Show token validity
+    println!("Token validity:");
+    println!("  Alice's token expires in {} days", alice_token.remaining_validity() / 86400);
+    println!("  Bob's token expires in {} days", bob_token.remaining_validity() / 86400);
+    println!();
+
+    println!("=== Success! ===\n");
+    println!("Next steps:");
+    println!("  1. Share these tokens out-of-band (QR code, secure chat, etc.)");
+    println!("  2. Verify fingerprints match in person or via call");
+    println!("  3. Use the handshake protocol to establish encrypted sessions");
+    println!("  4. See 'handshake_example' for the full flow");
+
+    Ok(())
+}

IMPLEMENT.md

@@ -0,0 +1,116 @@
+//! Crypto Primitives Example
+//!
+//! This example demonstrates direct usage of the cryptographic primitives:
+//! - X25519 key exchange
+//! - Kyber768 post-quantum KEM
+//! - Ed25519 signatures
+//! - Dilithium3 post-quantum signatures
+//! - ChaCha20-Poly1305 AEAD
+//!
+//! Run with: cargo run --example crypto_primitives
+
+use lmp_core::crypto::{aead, dilithium, ed25519, hkdf, kyber, x25519};
+use lmp_core::error::Result;
+
+fn main() -> Result<()> {
+    println!("=== LMP Cryptographic Primitives Demo ===\n");
+
+    // X25519 Key Exchange
+    println!("1. X25519 Elliptic Curve Diffie-Hellman");
+    println!("   ────────────────────────────────────");
+    let (alice_x25519_pub, alice_x25519_sec) = x25519::generate_keypair()?;
+    let (bob_x25519_pub, bob_x25519_sec) = x25519::generate_keypair()?;
+    
+    let alice_shared = x25519::diffie_hellman(&alice_x25519_sec, &bob_x25519_pub)?;
+    let bob_shared = x25519::diffie_hellman(&bob_x25519_sec, &alice_x25519_pub)?;
+    
+    println!("   Alice's public key: {}...", hex::encode(&alice_x25519_pub[..8]));
+    println!("   Bob's public key:   {}...", hex::encode(&bob_x25519_pub[..8]));
+    println!("   Shared secret:      {}...", hex::encode(&alice_shared[..8]));
+    println!("   Secrets match:      {}", alice_shared == bob_shared);
+    println!();
+
+    // Kyber768 Post-Quantum KEM
+    println!("2. Kyber768 Post-Quantum Key Encapsulation");
+    println!("   ────────────────────────────────────────");
+    let (kyber_pk, kyber_sk) = kyber::generate_keypair()?;
+    
+    let (ciphertext, shared_sender) = kyber::encapsulate(&kyber_pk)?;
+    let shared_receiver = kyber::decapsulate(&ciphertext, &kyber_sk)?;
+    
+    println!("   Public key size:    {} bytes", kyber_pk.len());
+    println!("   Secret key size:    {} bytes", kyber_sk.len());
+    println!("   Ciphertext size:    {} bytes", ciphertext.len());
+    println!("   Shared secret:      {}...", hex::encode(&shared_sender[..8]));
+    println!("   Secrets match:      {}", shared_sender == shared_receiver);
+    println!();
+
+    // Ed25519 Signatures
+    println!("3. Ed25519 Digital Signatures");
+    println!("   ──────────────────────────");
+    let (ed_pub, ed_sec) = ed25519::generate_keypair()?;
+    let message = b"This is a test message for signing";
+    
+    let signature = ed25519::sign(message, &ed_sec, &ed_pub)?;
+    let verify_result = ed25519::verify(message, &signature, &ed_pub);
+    
+    println!("   Message:           \"{}\"", String::from_utf8_lossy(message));
+    println!("   Signature size:    {} bytes", signature.len());
+    println!("   Signature valid:   {}", verify_result.is_ok());
+    println!();
+
+    // Dilithium3 Post-Quantum Signatures
+    println!("4. Dilithium3 Post-Quantum Signatures");
+    println!("   ───────────────────────────────────");
+    let (dil_pk, dil_sk) = dilithium::generate_keypair()?;
+    
+    let dil_sig = dilithium::sign(message, &dil_sk)?;
+    let dil_verify = dilithium::verify(message, &dil_sig, &dil_pk);
+    
+    println!("   Public key size:   {} bytes", dil_pk.len());
+    println!("   Secret key size:   {} bytes", dil_sk.len());
+    println!("   Signature size:    {} bytes", dil_sig.len());
+    println!("   Signature valid:   {}", dil_verify.is_ok());
+    println!();
+
+    // ChaCha20-Poly1305 AEAD
+    println!("5. ChaCha20-Poly1305 Authenticated Encryption");
+    println!("   ──────────────────────────────────────────");
+    let mut rng = lmp_core::crypto::rng::SecureRng::new();
+    let mut key = [0u8; 32];
+    rng.fill_bytes(&mut key)?;
+    
+    let aead_cipher = aead::Aead::new(key);
+    let nonce = [0u8; 12];
+    let aad = b"additional data";
+    let plaintext = b"Secret message to encrypt!";
+    
+    let ciphertext = aead_cipher.encrypt(&nonce, plaintext, aad)?;
+    let decrypted = aead_cipher.decrypt(&nonce, &ciphertext, aad)?;
+    
+    println!("   Key:               {}...", hex::encode(&key[..8]));
+    println!("   Plaintext:         \"{}\"", String::from_utf8_lossy(plaintext));
+    println!("   Ciphertext size:   {} bytes (includes 16-byte auth tag)", ciphertext.len());
+    println!("   Decrypted:         \"{}\"", String::from_utf8_lossy(&decrypted));
+    println!("   Decryption OK:     {}", plaintext == decrypted.as_slice());
+    println!();
+
+    // HKDF Key Derivation
+    println!("6. HKDF-SHA3-256 Key Derivation");
+    println!("   ────────────────────────────");
+    let salt = b"example salt";
+    let ikm = b"input key material";
+    let info = b"application context";
+    
+    let derived = hkdf::Hkdf::derive_key(salt, ikm, info)?;
+    
+    println!("   Input key material: \"{}\"", String::from_utf8_lossy(ikm));
+    println!("   Salt:               \"{}\"", String::from_utf8_lossy(salt));
+    println!("   Info:               \"{}\"", String::from_utf8_lossy(info));
+    println!("   Derived key:        {}...", hex::encode(&derived[..16]));
+    println!();
+
+    println!("=== All primitives working correctly! ===");
+
+    Ok(())
+}