sal/vault/README.md

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

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:

#[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:

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.