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

---

## Table of Contents
- [Summary](#summary)
- [Main Components](#main-components)
- [Security Model](#security-model)
- [Quickstart & Usage Examples](#quickstart--usage-examples)
- [More Information](#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

```rust
// 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`](architecture.md)
- **Implementation Details:** See [`vault_impl_plan.md`](vault_impl_plan.md)
- **Build Instructions:** See [`build_instructions.md`](build_instructions.md)

---

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

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

```rust
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)

```rust
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

```text
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](build_instructions.md).