feat: Refactor kvstore and vault to use features and logging

- Remove hardcoded dependencies in kvstore Cargo.toml; use features instead. This allows for more flexible compilation for different targets (native vs. WASM). - Improve logging in vault crate using the `log` crate. This makes debugging easier and provides more informative output during execution. Native tests use `env_logger`, WASM tests use `console_log`. - Update README to reflect new logging best practices. - Add cfg attributes to native and wasm modules to improve clarity. - Update traits.rs to specify Send + Sync behavior expectations.
2025-05-15 16:42:19 +03:00
parent 7d7f94f114
commit cea2d7e655
17 changed files with 843 additions and 295 deletions
--- a/docs/native-wasm-build-plan.md
+++ b/docs/native-wasm-build-plan.md
@@ -0,0 +1,85 @@
+# Plan: Ensuring Native and WASM Builds Work for the Vault/KVStore System
+
+## Purpose
+This document outlines the steps and requirements to guarantee that both native (desktop/server) and WASM (browser) builds of the `vault` and `kvstore` crates work seamlessly, securely, and efficiently.
+
+---
+
+## 1. Architecture Principles
+- **Async/Await Everywhere:** All APIs must be async and runtime-agnostic (no Tokio requirement in library code).
+- **KVStore Trait:** Use an async trait for storage, with platform-specific implementations (sled for native, IndexedDB/idb for WASM).
+- **Conditional Compilation:** Use `#[cfg(target_arch = "wasm32")]` and `#[cfg(not(target_arch = "wasm32"))]` to select code and dependencies.
+- **No Blocking in WASM:** All I/O and crypto operations must be async and non-blocking in browser builds.
+- **WASM-Compatible Crypto:** Only use crypto crates that compile to WASM (e.g., `aes-gcm`, `chacha20poly1305`, `k256`, `rand_core`).
+- **Separation of Concerns:** All encryption and password logic resides in `vault`, not `kvstore`.
+- **Stateless and Session APIs:** Provide both stateless (context-passing) and session-based APIs in `vault`.
+
+---
+
+## 2. Cargo.toml and Dependency Management
+- **Native:**
+  - `[target.'cfg(not(target_arch = "wasm32"))'.dependencies]`
+    - `tokio` (with only supported features)
+    - `sled`
+- **WASM:**
+  - `[target.'cfg(target_arch = "wasm32")'.dependencies]`
+    - `idb`
+    - `wasm-bindgen`, `wasm-bindgen-futures`
+- **Crypto:**
+  - Only include crates that are WASM-compatible for both targets.
+- **No unconditional `tokio`** in `vault` or `kvstore`.
+
+---
+
+## 3. Code Organization
+- **KVStore Trait:**
+  - Define as async trait (using `async_trait`).
+  - Implement for sled (native) and idb (WASM), using `#[cfg]`.
+- **Vault:**
+  - All persistence must go through the KVStore trait.
+  - All cryptography must be WASM-compatible.
+  - No direct file or blocking I/O in WASM.
+- **Runtime:**
+  - Only use `tokio` in binaries or native-specific code.
+  - In WASM, use `wasm-bindgen-futures::spawn_local` for async tasks.
+
+---
+
+## 4. Platform-Specific Guidelines
+- **Native (Desktop/Server):**
+  - Use `sled` for storage.
+  - Use `tokio::task::spawn_blocking` for blocking I/O if needed.
+  - All async code should work with any runtime.
+- **WASM (Browser):**
+  - Use `idb` crate for IndexedDB storage.
+  - All code must be non-blocking and compatible with the browser event loop.
+  - Use `wasm-bindgen` and `wasm-bindgen-futures` for JS interop and async.
+  - Expose APIs with `#[wasm_bindgen]` for JS usage.
+
+---
+
+## 5. Testing
+- **Native:** `cargo test`
+- **WASM:** `cargo test --target wasm32-unknown-unknown --release` (or use `wasm-pack test`)
+- **Separate tests** for native and WASM backends in `tests/`.
+
+---
+
+## 6. Checklist for Compliance
+- [ ] No unconditional `tokio` usage in library code
+- [ ] All dependencies are WASM-compatible (where needed)
+- [ ] All storage goes through async KVStore trait
+- [ ] No blocking I/O or native-only APIs in WASM
+- [ ] All cryptography is WASM-compatible
+- [ ] Both stateless and session APIs are available in `vault`
+- [ ] All APIs are async and runtime-agnostic
+- [ ] Native and WASM tests both pass
+
+---
+
+## 7. References
+- See `docs/Architecture.md`, `docs/kvstore-vault-architecture.md`, and `docs/vault_impl_plan.md` for architectural background and rationale.
+
+---
+
+By following this plan, the codebase will be robust, portable, and secure on both native and browser platforms, and will adhere to all project architectural guidelines.
--- a/docs/vault.md
+++ b/docs/vault.md
@@ -0,0 +1,164 @@
+🧱 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.
--- a/docs/vault_impl_plan.md
+++ b/docs/vault_impl_plan.md
@@ -0,0 +1,276 @@
+# Vault Implementation Plan
+
+> **Design Principle:**
+> **The vault crate will provide both a stateless (context-passing) API and an ergonomic session-based API.**
+> This ensures maximum flexibility for both library developers and application builders, supporting both functional and stateful usage patterns.
+
+## 1. Architecture Overview
+
+The `vault` crate is a modular, async, and WASM-compatible cryptographic keystore. It manages an encrypted keyspace (multiple keypairs), provides cryptographic APIs, and persists all data via the `kvstore` trait. The design ensures all sensitive material is encrypted at rest and is portable across native and browser environments.
+
+**Core Components:**
+- **Vault:** Main manager for encrypted keyspace and cryptographic operations.
+- **KeyPair:** Represents individual asymmetric keypairs (e.g., secp256k1, Ed25519).
+- **Symmetric Encryption Module:** Handles encryption/decryption and key derivation.
+- **SessionManager (Optional):** Maintains current context (e.g., selected keypair) for user sessions.
+- **KVStore:** Async trait for backend-agnostic persistence (sled on native, IndexedDB on WASM).
+
+---
+
+## Using Both Stateless and Session-Based APIs
+
+You can design the vault crate to support both stateless and session-based (stateful) usage patterns. This gives maximum flexibility to both library developers and application builders.
+
+### Stateless API
+- All operations require explicit context (unlocked keyspace, keypair, etc.) as arguments.
+- No hidden or global state; maximally testable and concurrency-friendly.
+- Example:
+  ```rust
+  let keyspace = vault.unlock_keyspace("personal", b"password").await?;
+  let signature = keyspace.sign("key1", &msg).await?;
+  ```
+
+### Session Manager API
+- Maintains in-memory state of unlocked keyspaces and current selections.
+- Provides ergonomic methods for interactive apps (CLI, desktop, browser).
+- Example:
+  ```rust
+  let mut session = SessionManager::new();
+  session.unlock_keyspace("personal", b"password", &vault)?;
+  session.select_keypair("key1");
+  let signature = session.current_keypair().unwrap().sign(&msg)?;
+  session.logout(); // wipes all secrets from memory
+  ```
+
+### How They Work Together
+- The **stateless API** is the core, always available and used internally by the session manager.
+- The **session manager** is a thin, optional layer that wraps the stateless API for convenience.
+- Applications can choose which pattern fits their needs, or even mix both (e.g., use stateless for background jobs, session manager for user sessions).
+
+### Benefits
+- **Flexibility:** Library users can pick the best model for their use case.
+- **Security:** Session manager can enforce auto-lock, timeouts, and secure memory wiping.
+- **Simplicity:** Stateless API is easy to test and reason about, while session manager improves UX for interactive flows.
+
+### Commitment: Provide Both APIs
+- **Both stateless and session-based APIs will be provided in the vault crate.**
+- Stateless API: For backend, automation, or library contexts—explicit, functional, and concurrency-friendly.
+- Session manager API: For UI/UX-focused applications—ergonomic, stateful, and user-friendly.
+
+---
+
+## 2. Data Model
+
+### VaultMetadata & Keyspace Model
+```rust
+struct VaultMetadata {
+    name: String,
+    keyspaces: Vec<KeyspaceMetadata>,
+    // ... other vault-level metadata (optionally encrypted)
+}
+
+struct KeyspaceMetadata {
+    name: String,
+    salt: [u8; 16], // Unique salt for this keyspace
+    encrypted_blob: Vec<u8>, // All keypairs & secrets, encrypted with keyspace password
+    // ... other keyspace metadata
+}
+
+// The decrypted contents of a keyspace:
+struct KeyspaceData {
+    keypairs: Vec<KeyEntry>,
+    // ... other keyspace-level metadata
+}
+
+struct KeyEntry {
+    id: String,
+    key_type: KeyType,
+    private_key: Vec<u8>, // Only present in memory after decryption
+    public_key: Vec<u8>,
+    metadata: Option<KeyMetadata>,
+}
+
+enum KeyType {
+    Secp256k1,
+    Ed25519,
+    // ...
+}
+```
+
+- The vault contains a list of keyspaces, each with its own salt and encrypted blob.
+- Each keyspace is unlocked independently using its password and salt.
+- Key material is never stored unencrypted; only decrypted in memory after unlocking a keyspace.
+
+---
+
+## 3. API Design (Keyspace Model)
+
+### Vault
+```rust
+impl<S: KVStore + Send + Sync> Vault<S> {
+    async fn open(store: S) -> Result<Self, VaultError>;
+    async fn list_keyspaces(&self) -> Result<Vec<KeyspaceInfo>, VaultError>;
+    async fn create_keyspace(&mut self, name: &str, password: &[u8]) -> Result<(), VaultError>;
+    async fn delete_keyspace(&mut self, name: &str) -> Result<(), VaultError>;
+    async fn unlock_keyspace(&mut self, name: &str, password: &[u8]) -> Result<(), VaultError>;
+    async fn lock_keyspace(&mut self, name: &str);
+    // ...
+}
+```
+
+### Keyspace Management
+```rust
+impl Keyspace {
+    fn is_unlocked(&self) -> bool;
+    fn name(&self) -> &str;
+    async fn create_key(&mut self, key_type: KeyType, name: &str) -> Result<String, VaultError>;
+    async fn list_keys(&self) -> Result<Vec<KeyInfo>, VaultError>;
+    async fn sign(&self, key_id: &str, msg: &[u8]) -> Result<Signature, VaultError>;
+    async fn encrypt(&self, key_id: &str, plaintext: &[u8]) -> Result<Ciphertext, VaultError>;
+    async fn decrypt(&self, key_id: &str, ciphertext: &[u8]) -> Result<Vec<u8>, VaultError>;
+    async fn change_password(&mut self, old: &[u8], new: &[u8]) -> Result<(), VaultError>;
+    // ...
+}
+```
+
+### SessionManager
+```rust
+impl SessionManager {
+    fn select_key(&mut self, key_id: &str);
+    fn current_key(&self) -> Option<&KeyPair>;
+}
+```
+
+### Symmetric Encryption Module
+- Derives a master key from password and salt (e.g., PBKDF2 or scrypt).
+- Encrypts/decrypts vault data with AES-GCM or ChaCha20Poly1305.
+
+---
+
+## 4. Implementation Plan
+
+1. **Define Data Structures**
+    - VaultData, KeyEntry, KeyType, KeyMetadata, etc.
+2. **Implement Symmetric Encryption**
+    - Password-based key derivation (PBKDF2/scrypt)
+    - AES-GCM or ChaCha20Poly1305 encryption
+3. **Vault Logic**
+    - open, unlock, encrypt/decrypt, manage keypairs
+    - persist encrypted blob in kvstore
+4. **KeyPair Management**
+    - Generate, import, export, sign, verify
+5. **Session Management**
+    - Track selected key/context
+6. **Error Handling**
+    - VaultError enum for crypto, storage, and logic errors
+7. **WASM Interop**
+    - Use wasm-bindgen to expose async APIs as JS Promises
+    - Ensure all crypto crates are WASM-compatible
+8. **Testing**
+    - Native and WASM tests for all APIs
+
+---
+
+## Design Decisions: Old Implementation, Current Plan, Open Questions, and Recommendations
+
+| Area | Old Implementation | Current Plan | Decision Left/Open | Recommendation & Rationale |
+|------|--------------------|--------------|--------------------|----------------------------|
+| **KDF** | PBKDF2-HMAC-SHA256 | PBKDF2 or scrypt (WASM-compatible) | Which as default? Both supported? Per-keyspace choice? | **Use scrypt as default** for new keyspaces (stronger against GPU attacks)
+| **Symmetric Encryption** | ChaCha20Poly1305 | AES-256-GCM or ChaCha20Poly1305 | Which default? Both supported? Per-keyspace choice? | **ChaCha20Poly1305 recommended** for WASM and cross-platform.
+| **Key Types** | secp256k1, Ed25519 | secp256k1, Ed25519 | Add more? Custom key types? | **Keep secp256k1 and Ed25519 as default.** |
+| **Metadata Encryption** | Unencrypted vault metadata | Unencrypted keyspace metadata | Option to encrypt metadata? | **Unencrypted vault metadata** for simplicity. |
+| **Session Manager Features** | No session manager, manual unlock | Optional session manager | Timeout, auto-lock, secure wipe, multi-user? | **Implement optional session manager with timeout and secure memory wipe**. |
+| **Password Change/Recovery** | Manual re-encrypt, no recovery | API for password change | Re-encrypt all? Recovery/MFA? | **Re-encrypt keyspace on password change.** |
+| **WASM/Native Crypto** | Native only | WASM-compatible crates | Native-only features? | **Require WASM compatibility for all core features.** |
+| **Keyspace Sharing/Export** | Manual export/import, share password | Share keyspace password | Explicit export/import flows? Auditing? | **Add explicit export/import APIs.** Log/audit sharing if privacy is a concern. |
+| **Multi-user/Access Control** | Single password per vault | Single password per keyspace | ACL, threshold unlock? | **Single password per keyspace is simplest.** |
+| **Metadata/Tagging** | Minimal metadata, no tags | Basic metadata, optional tags | Required/custom tags? Usage stats? | **Support custom tags and creation date** for keyspaces/keys. |
+| **Storage Structure** | Single JSON file (vault) | Keyspaces as blobs in vault metadata | Store as separate kvstore records? | **Recommend storing each keyspace as a separate record** in kvstore for easier backup/sync/restore. |
+| **Error Handling** | Basic error codes | VaultError enum | Granular or coarse? WASM/JS exposure? | **Define granular error types** and expose user-friendly errors for WASM/JS. |
+
+---
+
+**Legend:**
+- **Old Implementation:** What was done in the previous (legacy) design.
+- **Current Plan:** What is currently proposed in this implementation plan.
+- **Decision Left/Open:** What remains to be finalized or clarified.
+- **Recommendation & Rationale:** What is recommended for the new implementation and why, especially if it differs from the old approach.
+
+---
+
+## 5. File/Module Structure (Recommended)
+
+```
+vault/
+├── src/
+│   ├── lib.rs            # Vault API and main logic
+│   ├── data.rs           # Data models: VaultData, KeyEntry, etc.
+│   ├── crypto.rs         # Symmetric/asymmetric crypto, key derivation
+│   ├── session.rs        # SessionManager
+│   ├── error.rs          # VaultError and error handling
+│   └── utils.rs          # Helpers, serialization, etc.
+├── tests/
+│   ├── native.rs         # Native (sled) tests
+│   └── wasm.rs           # WASM (IndexedDB) tests
+└── ...
+```
+
+---
+
+## 6. Cryptography: Crates and Algorithms
+
+**Crates:**
+- [`aes-gcm`](https://crates.io/crates/aes-gcm): AES-GCM authenticated encryption (WASM-compatible)
+- [`chacha20poly1305`](https://crates.io/crates/chacha20poly1305): ChaCha20Poly1305 authenticated encryption (WASM-compatible)
+- [`pbkdf2`](https://crates.io/crates/pbkdf2): Password-based key derivation (WASM-compatible)
+- [`scrypt`](https://crates.io/crates/scrypt): Alternative KDF, strong and WASM-compatible
+- [`k256`](https://crates.io/crates/k256): secp256k1 ECDSA (Ethereum keys)
+- [`ed25519-dalek`](https://crates.io/crates/ed25519-dalek): Ed25519 keypairs
+- [`rand_core`](https://crates.io/crates/rand_core): Randomness, WASM-compatible
+- [`getrandom`](https://crates.io/crates/getrandom): Platform-agnostic RNG
+
+**Algorithm Choices:**
+- **Vault Encryption:**
+  - AES-256-GCM (default, via `aes-gcm`)
+  - Optionally ChaCha20Poly1305 (via `chacha20poly1305`)
+- **Password Key Derivation:**
+  - PBKDF2-HMAC-SHA256 (via `pbkdf2`)
+  - Optionally scrypt (via `scrypt`)
+- **Asymmetric Keypairs:**
+  - secp256k1 (via `k256`) for Ethereum/EVM
+  - Ed25519 (via `ed25519-dalek`) for general-purpose signatures
+- **Randomness:**
+  - Use `rand_core` and `getrandom` for secure RNG in both native and WASM
+
+**Feature-to-Algorithm Mapping:**
+| Feature                | Crate(s)              | Algorithm(s)              |
+|------------------------|-----------------------|---------------------------|
+| Vault encryption       | aes-gcm, chacha20poly1305 | AES-256-GCM, ChaCha20Poly1305 |
+| Password KDF           | pbkdf2, scrypt        | PBKDF2-HMAC-SHA256, scrypt|
+| Symmetric encryption   | aes-gcm, chacha20poly1305 | AES-256-GCM, ChaCha20Poly1305 |
+| secp256k1 keypairs     | k256                  | secp256k1 ECDSA           |
+| Ed25519 keypairs       | ed25519-dalek         | Ed25519                   |
+| Randomness             | rand_core, getrandom  | OS RNG                    |
+
+---
+
+## 7. WASM & Native Considerations
+- Use only WASM-compatible crypto crates (`aes-gcm`, `chacha20poly1305`, `k256`, `ed25519-dalek`, etc).
+- Use `wasm-bindgen`/`wasm-bindgen-futures` for browser interop.
+- Use `tokio::task::spawn_blocking` for blocking crypto on native.
+- All APIs are async and runtime-agnostic.
+
+---
+
+## 6. Future Extensions
+- Multi-user vaults (multi-password, access control)
+- Hardware-backed key storage (YubiKey, WebAuthn)
+- Key rotation and auditing
+- Pluggable crypto algorithms
+- Advanced metadata and tagging
+
+---
+
+## 7. References
+- See `docs/Architecture.md` and `docs/kvstore-vault-architecture.md` for high-level design and rationale.
+- Crypto patterns inspired by industry best practices (e.g., Wire, Signal, Bitwarden).