# SAL Vault

A secure, encrypted key-value store system for the System Abstraction Layer (SAL).

## Overview

SAL Vault provides a two-tiered encrypted storage system:

1. **Vault**: A collection of encrypted keyspaces
2. **KeySpace**: An individual encrypted key-value store within a vault

## Features

- **Secure Storage**: ChaCha20Poly1305 encryption for all data
- **Password-Based Encryption**: Keyspaces are encrypted using password-derived keys
- **Cross-Platform**: Works on both native and WASM targets
- **Async API**: Fully asynchronous operations
- **Type Safety**: Strong typing with comprehensive error handling

## Architecture

```
Vault
├── KeySpace 1 (encrypted with password A)
├── KeySpace 2 (encrypted with password B)
└── KeySpace N (encrypted with password N)
```

Each keyspace is independently encrypted, allowing different access controls and security boundaries.

## Usage

### Creating a Vault

```rust
use sal_vault::{Vault, Error};
use std::path::Path;

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Create a new vault at the specified path
    let vault = Vault::new(Path::new("./my_vault")).await?;
    
    // Open an encrypted keyspace
    let keyspace = vault.open_keyspace("user_data", "secure_password").await?;
    
    // Use the keyspace for encrypted storage
    // (KeySpace API documentation coming soon)
    
    Ok(())
}
```

### WASM Support

The vault also supports WASM targets with browser-compatible storage:

```rust
#[cfg(target_arch = "wasm32")]
async fn wasm_example() -> Result<(), Error> {
    let vault = Vault::new().await?; // No path needed for WASM
    let keyspace = vault.open_keyspace("session_data", "password").await?;
    Ok(())
}
```

## Security

### Encryption

- **Algorithm**: ChaCha20Poly1305 (AEAD)
- **Key Derivation**: PBKDF2 with secure parameters
- **Nonce Generation**: Cryptographically secure random nonces
- **Authentication**: Built-in authentication prevents tampering

### Best Practices

1. **Strong Passwords**: Use strong, unique passwords for each keyspace
2. **Secure Storage**: Store vault files in secure locations
3. **Access Control**: Limit filesystem access to vault directories
4. **Backup Strategy**: Implement secure backup procedures
5. **Key Rotation**: Periodically change keyspace passwords

## Error Handling

The vault uses a comprehensive error system:

```rust
use sal_vault::Error;

match vault.open_keyspace("test", "password").await {
    Ok(keyspace) => {
        // Success - use the keyspace
    }
    Err(Error::IOError(io_err)) => {
        // Handle I/O errors (file system issues)
    }
    Err(Error::CryptoError(crypto_err)) => {
        // Handle cryptographic errors (wrong password, corruption)
    }
    Err(other) => {
        // Handle other errors
    }
}
```

## Migration from Previous Implementation

This vault implementation replaces the previous Ethereum-focused vault. Key differences:

### What's New
- ✅ Simpler, more focused API
- ✅ Better cross-platform support
- ✅ Improved security model
- ✅ Cleaner error handling

### What's Changed
- ❌ No Ethereum wallet functionality
- ❌ No smart contract integration
- ❌ No built-in signing operations
- ⏳ Rhai scripting integration (coming soon)

### Archived Implementation

The previous implementation is preserved in `_archive/` for reference and potential feature extraction.

## Development Status

- ✅ **Core Vault**: Complete and functional
- ✅ **KeySpace Operations**: Basic implementation ready
- ✅ **Encryption**: Secure ChaCha20Poly1305 implementation
- ⏳ **Rhai Integration**: In development
- ⏳ **Extended API**: Additional convenience methods planned
- ⏳ **Documentation**: API docs being completed

## Contributing

When contributing to the vault module:

1. Maintain security-first approach
2. Ensure cross-platform compatibility
3. Add comprehensive tests for new features
4. Update documentation for API changes
5. Consider WASM compatibility for new features

## License

This module is part of the SAL project and follows the same licensing terms.