sal-modular/docs/vault.md

🧱 Vault Crate Architecture
1. VaultStore
Purpose: Central manager for all keyspaces.

Responsibilities:

Maintain metadata about keyspaces.

Provide interfaces to create, load, and manage keyspaces.

Ensure each keyspace is encrypted with its own password.

2. KeySpace
Purpose: Isolated environment containing multiple keypairs.

Responsibilities:

Securely store and manage keypairs.

Provide cryptographic operations like signing and encryption.

Handle encryption/decryption using a password-derived key.

3. KeyPair
Purpose: Represents an individual cryptographic keypair.

Responsibilities:

Perform cryptographic operations such as signing and verification.

Support key export and import functionalities.

4. Symmetric Encryption Module
Purpose: Provides encryption and decryption functionalities.

Responsibilities:

Encrypt and decrypt data using algorithms like ChaCha20Poly1305.

Derive encryption keys from passwords using PBKDF2.

5. SessionManager
Purpose: Manages the active context for cryptographic operations, simplifying API usage.

Responsibilities:

Maintain the currently selected keypair.

Provide simplified methods for cryptographic operations without repeatedly specifying the keypair.

🔐 Security Model
Per-KeySpace Encryption: Each keyspace is encrypted independently using a key derived from its password.

VaultStore Metadata: Stores non-sensitive metadata about keyspaces, such as their names and creation dates. This metadata can be stored in plaintext or encrypted based on security requirements.

🧪 API Design
VaultStore
rust
Copy
Edit
pub struct VaultStore {
    // Internal fields
}

impl VaultStore {
    pub fn new() -> Self;
    pub fn load() -> Result<Self, VaultError>;
    pub fn save(&self) -> Result<(), VaultError>;

    pub fn list_keyspaces(&self) -> Vec<KeyspaceMetadata>;
    pub fn create_keyspace(&mut self, name: &str, password: &str) -> Result<(), VaultError>;
    pub fn delete_keyspace(&mut self, name: &str) -> Result<(), VaultError>;
    pub fn rename_keyspace(&mut self, old_name: &str, new_name: &str) -> Result<(), VaultError>;
    pub fn load_keyspace(&self, name: &str, password: &str) -> Result<KeySpace, VaultError>;
}
KeySpace
rust
Copy
Edit
pub struct KeySpace {
    // Internal fields
}

impl KeySpace {
    pub fn new(name: &str, password: &str) -> Result<Self, VaultError>;
    pub fn save(&self) -> Result<(), VaultError>;

    pub fn list_keypairs(&self) -> Vec<String>;
    pub fn create_keypair(&mut self, name: &str) -> Result<(), VaultError>;
    pub fn delete_keypair(&mut self, name: &str) -> Result<(), VaultError>;
    pub fn rename_keypair(&mut self, old_name: &str, new_name: &str) -> Result<(), VaultError>;
    pub fn get_keypair(&self, name: &str) -> Result<KeyPair, VaultError>;

    pub fn sign(&self, keypair_name: &str, message: &[u8]) -> Result<Vec<u8>, VaultError>;
    pub fn verify(&self, keypair_name: &str, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
}
KeyPair
rust
Copy
Edit
pub struct KeyPair {
    // Internal fields
}

impl KeyPair {
    pub fn new() -> Self;
    pub fn from_private_key(private_key: &[u8]) -> Result<Self, VaultError>;

    pub fn public_key(&self) -> Vec<u8>;
    pub fn private_key(&self) -> Vec<u8>;

    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, VaultError>;
    pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
}
SessionManager (Optional)
rust
Copy
Edit
pub struct SessionManager {
    keyspace: KeySpace,
    active_keypair: String,
}

impl SessionManager {
    pub fn new(keyspace: KeySpace, keypair_name: &str) -> Result<Self, VaultError>;
    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, VaultError>;
    pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, VaultError>;
    pub fn switch_keypair(&mut self, keypair_name: &str) -> Result<(), VaultError>;
}
📦 Storage Structure
Copy
Edit
vault_store/
├── metadata.json
└── keyspaces/
    ├── alice.ksp
    ├── bob.ksp
    └── ...
metadata.json: Contains metadata about each keyspace, such as name and creation date.

keyspaces/: Directory containing encrypted keyspace files.

🔄 Integration with kvstore
Native Environment
Storage Backend: Utilize the local filesystem or a persistent database (e.g., SQLite) for storing VaultStore and KeySpace data.

Usage:

Initialize VaultStore and load existing keyspaces.

Perform cryptographic operations using KeySpace and KeyPair.

Persist changes to disk or database.

Browser Environment (WASM)
Storage Backend: Use browser storage APIs like localStorage or IndexedDB for persisting data.

Usage:

Compile the vault crate to WebAssembly.

Interact with the vault API through JavaScript bindings.

Store and retrieve encrypted keyspaces using browser storage.