Feat: simplify vault API and update docs
This commit is contained in:
@@ -1,10 +1,23 @@
|
||||
# Vault Implementation Plan
|
||||
# Vault Implementation Plan (Technical Appendix)
|
||||
|
||||
This document is a technical reference for contributors and maintainers of the Vault crate. It covers advanced implementation details, design rationale, and data models. For a high-level overview and usage, see [`vault.md`](vault.md) and [`architecture.md`](architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
- [Design Principle: Stateless & Session APIs](#design-principle-stateless--session-apis)
|
||||
- [Data Model](#data-model)
|
||||
- [Module & File Structure](#module--file-structure)
|
||||
- [Advanced Notes](#advanced-notes)
|
||||
|
||||
---
|
||||
|
||||
|
||||
> **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
|
||||
## Design Principle: Stateless & Session APIs
|
||||
|
||||
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.
|
||||
|
||||
@@ -15,9 +28,7 @@ The `vault` crate is a modular, async, and WASM-compatible cryptographic keystor
|
||||
- **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.
|
||||
|
||||
@@ -59,7 +70,7 @@ You can design the vault crate to support both stateless and session-based (stat
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Model
|
||||
## Data Model
|
||||
|
||||
### VaultMetadata & Keyspace Model
|
||||
```rust
|
||||
@@ -141,64 +152,6 @@ impl SessionManager {
|
||||
}
|
||||
```
|
||||
|
||||
### 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/
|
||||
@@ -217,7 +170,12 @@ vault/
|
||||
|
||||
---
|
||||
|
||||
## 6. Cryptography: Crates and Algorithms
|
||||
## Advanced Notes
|
||||
|
||||
- For further context on cryptographic choices, async patterns, and WASM compatibility, see `architecture.md`.
|
||||
- This appendix is intended for developers extending or maintaining the Vault implementation.
|
||||
|
||||
### Cryptography: Crates and Algorithms
|
||||
|
||||
**Crates:**
|
||||
- [`aes-gcm`](https://crates.io/crates/aes-gcm): AES-GCM authenticated encryption (WASM-compatible)
|
||||
|
||||
Reference in New Issue
Block a user