sal/vault/_archive/src/keyspace/README.md

# Hero Vault Keypair Module

The Keypair module provides functionality for creating, managing, and using ECDSA keypairs for digital signatures and other cryptographic operations.

## Module Structure

The Keypair module is organized into:

- `keypair_types.rs` - Defines the KeyPair and related types.
- `session_manager.rs` - Implements the core logic for managing keypairs and key spaces.
- `mod.rs` - Module exports and public interface.

## Key Types

### KeyPair

The `KeyPair` type represents an ECDSA keypair used for digital signatures and other cryptographic operations.

```rust
pub struct KeyPair {
    // Private fields
    // ...
}

impl KeyPair {
    // Create a new random keypair
    pub fn new() -> Result<Self, CryptoError>;
    
    // Create a keypair from an existing private key
    pub fn from_private_key(private_key: &[u8]) -> Result<Self, CryptoError>;
    
    // Get the public key
    pub fn public_key(&self) -> &[u8];
    
    // Sign a message
    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, CryptoError>;
    
    // Verify a signature
    pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, CryptoError>;
    
    // Derive an Ethereum address from the public key
    pub fn to_ethereum_address(&self) -> Result<String, CryptoError>;
    
    // Export the private key (should be used with caution)
    pub fn export_private_key(&self) -> Result<Vec<u8>, CryptoError>;
}
```

### KeySpace

The `KeySpace` type represents a secure container for multiple keypairs, which can be encrypted and stored on disk.

```rust
pub struct KeySpace {
    // Private fields
    // ...
}

impl KeySpace {
    // Create a new key space
    pub fn new(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // Load a key space from disk
    pub fn load(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // Save the key space to disk
    pub fn save(&self) -> Result<(), CryptoError>;
    
    // Create a new keypair in the key space
    pub fn create_keypair(&mut self, name: &str, password: &str) -> Result<&KeyPair, CryptoError>;
    
    // Select a keypair for use
    pub fn select_keypair(&mut self, name: &str) -> Result<&KeyPair, CryptoError>;
    
    // Get the currently selected keypair
    pub fn current_keypair(&self) -> Result<&KeyPair, CryptoError>;
    
    // List all keypairs in the key space
    pub fn list_keypairs(&self) -> Result<Vec<String>, CryptoError>;
    
    // Get a keypair by name
    pub fn get_keypair(&self, name: &str) -> Result<&KeyPair, CryptoError>;
    
    // Remove a keypair from the key space
    pub fn remove_keypair(&mut self, name: &str) -> Result<(), CryptoError>;
    
    // Rename a keypair
    pub fn rename_keypair(&mut self, old_name: &str, new_name: &str) -> Result<(), CryptoError>;
    
    // Get the name of the key space
    pub fn name(&self) -> &str;
}
```

## Key Features

### Key Space Management

The module provides functionality for creating, loading, and managing key spaces:

```rust
// Create a new key space
let mut space = KeySpace::new("my_space", "secure_password")?;

// Save the key space to disk
space.save()?;

// Load a key space from disk
let mut loaded_space = KeySpace::load("my_space", "secure_password")?;
```

### Keypair Management

The module provides functionality for creating, selecting, and using keypairs:

```rust
use crate::vault::keypair::{KeySpace, KeyPair};
use crate::vault::error::CryptoError; // Assuming CryptoError is in vault::error

fn demonstrate_keypair_management() -> Result<(), CryptoError> {
    // Create a new key space
    let mut space = KeySpace::new("my_space", "secure_password")?;

    // Create a new keypair in the key space
    let keypair = space.create_keypair("my_keypair", "secure_password")?;
    println!("Created keypair: {}", keypair.public_key().iter().map(|b| format!("{:02x}", b)).collect::<String>());

    // Select a keypair for use
    space.select_keypair("my_keypair")?;
    println!("Selected keypair: {}", space.current_keypair()?.public_key().iter().map(|b| format!("{:02x}", b)).collect::<String>());

    // List all keypairs in the key space
    let keypairs = space.list_keypairs()?;
    println!("Keypairs in space: {:?}", keypairs);

    // Get a keypair by name
    let retrieved_keypair = space.get_keypair("my_keypair")?;
    println!("Retrieved keypair: {}", retrieved_keypair.public_key().iter().map(|b| format!("{:02x}", b)).collect::<String>());

    // Rename a keypair
    space.rename_keypair("my_keypair", "new_name")?;
    println!("Renamed keypair to new_name");
    let keypairs_after_rename = space.list_keypairs()?;
    println!("Keypairs in space after rename: {:?}", keypairs_after_rename);


    // Remove a keypair from the key space
    space.remove_keypair("new_name")?;
    println!("Removed keypair new_name");
    let keypairs_after_remove = space.list_keypairs()?;
    println!("Keypairs in space after removal: {:?}", keypairs_after_remove);

    Ok(())
}
```

### Digital Signatures

The module provides functionality for signing and verifying messages using ECDSA:

```rust
use crate::vault::keypair::KeySpace;
use crate::vault::error::CryptoError; // Assuming CryptoError is in vault::error

fn demonstrate_digital_signatures() -> Result<(), CryptoError> {
    // Assuming a key space and selected keypair exist
    // let mut space = KeySpace::load("my_space", "secure_password")?; // Load existing space
    let mut space = KeySpace::new("temp_space_for_demo", "password")?; // Or create a new one for demo
    space.create_keypair("my_signing_key", "key_password")?;
    space.select_keypair("my_signing_key")?;


    // Sign a message using the selected keypair
    let keypair = space.current_keypair()?;
    let message = "This is a message to sign".as_bytes();
    let signature = keypair.sign(message)?;
    println!("Message signed. Signature: {:?}", signature);

    // Verify a signature
    let is_valid = keypair.verify(message, &signature)?;
    println!("Signature valid: {}", is_valid);

    // Example of invalid signature verification
    let invalid_signature = vec![0u8; signature.len()]; // A dummy invalid signature
    let is_valid_invalid = keypair.verify(message, &invalid_signature)?;
    println!("Invalid signature valid: {}", is_valid_invalid);


    Ok(())
}
```

### Ethereum Address Derivation

The module provides functionality for deriving Ethereum addresses from keypairs:

```rust
use crate::vault::keypair::KeySpace;
use crate::vault::error::CryptoError; // Assuming CryptoError is in vault::error

fn demonstrate_ethereum_address_derivation() -> Result<(), CryptoError> {
    // Assuming a key space and selected keypair exist
    // let mut space = KeySpace::load("my_space", "secure_password")?; // Load existing space
     let mut space = KeySpace::new("temp_space_for_eth_demo", "password")?; // Or create a new one for demo
    space.create_keypair("my_eth_key", "key_password")?;
    space.select_keypair("my_eth_key")?;

    // Derive an Ethereum address from a keypair
    let keypair = space.current_keypair()?;
    let address = keypair.to_ethereum_address()?;
    println!("Derived Ethereum address: {}", address);

    Ok(())
}
```

## Including in Your Project

To include the Hero Vault Keypair module in your Rust project, add the following to your `Cargo.toml` file:

```toml
[dependencies]
hero_vault = "0.1.0" # Replace with the actual version
```

Then, you can import and use the module in your Rust code:

```rust
use hero_vault::vault::keypair::{KeySpace, KeyPair};
use hero_vault::vault::error::CryptoError;
```

## Testing

Tests for the Keypair module are included within the source files, likely in `session_manager.rs` or `mod.rs` as inline tests.

To run the tests, navigate to the root directory of the project in your terminal and execute the following command:

```bash
cargo test --lib vault::keypair
```

This command will run all tests specifically within the `vault::keypair` module.

## Security Considerations

- Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password
- Private keys are never stored in plaintext
- The module uses secure random number generation for key creation
- All cryptographic operations use well-established libraries and algorithms

## Error Handling

The module uses the `CryptoError` type for handling errors that can occur during keypair operations:

- `InvalidKeyLength` - Invalid key length
- `SignatureFormatError` - Signature format error
- `KeypairAlreadyExists` - Keypair already exists
- `KeypairNotFound` - Keypair not found
- `NoActiveSpace` - No active key space
- `NoKeypairSelected` - No keypair selected
- `SerializationError` - Serialization error

## Examples

For examples of how to use the Keypair module, see the `examples/hero_vault` directory, particularly:

- `example.rhai` - Basic example demonstrating key management and signing
- `advanced_example.rhai` - Advanced example with error handling
- `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk
- `load_existing_space.rhai` - Shows how to load a previously created key space