sal-modular/docs/vault.md

Vault Crate Overview

Welcome to the Vault crate! This document provides a high-level overview, usage examples, and a guide to the main components of the Vault system. For deeper technical details, see architecture.md and vault_impl_plan.md.

---

Table of Contents

• Summary
• Main Components
• Security Model
• Quickstart & Usage Examples
• More Information

---

Summary

The Vault crate is a modular, async, and WASM-compatible cryptographic keystore. It manages encrypted keyspaces (each with multiple keypairs), provides cryptographic APIs, and persists all data via a pluggable key-value store. All sensitive material is always encrypted at rest.

---

Main Components

• VaultStore: Central manager for all keyspaces. Handles creation, loading, and metadata.
• KeySpace: Isolated environment containing multiple keypairs, encrypted with its own password.
• KeyPair: Represents an individual cryptographic keypair (e.g., secp256k1, Ed25519).
• Symmetric Encryption Module: Handles encryption/decryption using ChaCha20Poly1305 and PBKDF2.
• SessionManager (optional): Manages active context for ergonomic API usage (not required for stateless usage).

---

Security Model

• Per-KeySpace Encryption: Each keyspace is encrypted independently using a password-derived key.
• VaultStore Metadata: Stores non-sensitive metadata about keyspaces (names, creation dates, etc.).
• Zero-Knowledge: Passwords and keys are never stored in plaintext; all cryptographic operations are performed in memory.

---

Quickstart & Usage Examples

// Create a new VaultStore
let mut vault = VaultStore::new();

// Create a new keyspace
vault.create_keyspace("personal", "password123")?;

// List available keyspaces
let keyspaces = vault.list_keyspaces();

// Unlock a keyspace
let keyspace = vault.load_keyspace("personal", "password123")?;

// Create a new keypair
let key_id = keyspace.create_key(KeyType::Secp256k1, "mykey")?;

// Sign a message
let signature = keyspace.sign(&key_id, b"hello world")?;

---

More Information

• Architecture & Design: See architecture.md
• Implementation Details: See vault_impl_plan.md
• Build Instructions: See build_instructions.md

---

For advanced usage (stateless/session APIs, custom backends, WASM integration), see the linked documents above. }

KeySpace API Example

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 API Example

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 API Example (Optional)

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

vault_store/
├── metadata.json
└── keyspaces/
    ├── alice.ksp
    ├── bob.ksp
    └── ...

• metadata.json: Contains metadata about each keyspace, such as name and creation date.

Supported Environments

• Native: Uses filesystem or a database (e.g., SQLite) for storage.
• Browser (WASM): Uses IndexedDB or localStorage via the kvstore abstraction.

For full build and integration instructions, see build_instructions.md.