Feat: simplify vault API and update docs

2025-05-15 22:27:46 +03:00
parent cea2d7e655
commit 791752c3a5
21 changed files with 533 additions and 1106 deletions
--- a/docs/vault.md
+++ b/docs/vault.md
@@ -1,103 +1,92 @@
-🧱 Vault Crate Architecture
-1. VaultStore
-Purpose: Central manager for all keyspaces.
+# Vault Crate Overview

-Responsibilities:
+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`](architecture.md) and [`vault_impl_plan.md`](vault_impl_plan.md).

-Maintain metadata about keyspaces.
+---

-Provide interfaces to create, load, and manage keyspaces.
+## Table of Contents
+- [Summary](#summary)
+- [Main Components](#main-components)
+- [Security Model](#security-model)
+- [Quickstart & Usage Examples](#quickstart--usage-examples)
+- [More Information](#more-information)

-Ensure each keyspace is encrypted with its own password.
+---

-2. KeySpace
-Purpose: Isolated environment containing multiple keypairs.
+## 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.

-Responsibilities:
+---

-Securely store and manage keypairs.
+## 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).

-Provide cryptographic operations like signing and encryption.
+---

-Handle encryption/decryption using a password-derived key.
+## 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.

-3. KeyPair
-Purpose: Represents an individual cryptographic keypair.
+---

-Responsibilities:
+## Quickstart & Usage Examples

-Perform cryptographic operations such as signing and verification.
+```rust
+// Create a new VaultStore
+let mut vault = VaultStore::new();

-Support key export and import functionalities.
+// Create a new keyspace
+vault.create_keyspace("personal", "password123")?;

-4. Symmetric Encryption Module
-Purpose: Provides encryption and decryption functionalities.
+// List available keyspaces
+let keyspaces = vault.list_keyspaces();

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

-Encrypt and decrypt data using algorithms like ChaCha20Poly1305.
+// Create a new keypair
+let key_id = keyspace.create_key(KeyType::Secp256k1, "mykey")?;

-Derive encryption keys from passwords using PBKDF2.
+// Sign a message
+let signature = keyspace.sign(&key_id, b"hello world")?;
+```

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

-Responsibilities:
+## More Information
+- **Architecture & Design:** See [`architecture.md`](architecture.md)
+- **Implementation Details:** See [`vault_impl_plan.md`](vault_impl_plan.md)
+- **Build Instructions:** See [`build_instructions.md`](build_instructions.md)

-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
+*For advanced usage (stateless/session APIs, custom backends, WASM integration), see the linked documents above.*
 }

-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
-}
+### KeySpace API Example

+```rust
 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
+```
+
+### KeyPair API Example
+
+```rust
 pub struct KeyPair {
    // Internal fields
 }
@@ -105,17 +94,16 @@ pub struct KeyPair {
 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
+```
+
+### SessionManager API Example (Optional)
+
+```rust
 pub struct SessionManager {
    keyspace: KeySpace,
    active_keypair: String,
@@ -127,38 +115,24 @@ impl SessionManager {
    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
+```
+
+### Storage Structure
+
+```text
 vault_store/
 ├── metadata.json
 └── keyspaces/
    ├── alice.ksp
    ├── bob.ksp
    └── ...
-metadata.json: Contains metadata about each keyspace, such as name and creation date.
+```
+- `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.
+## Supported Environments

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

-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.
+For full build and integration instructions, see [build_instructions.md](build_instructions.md).