# 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:** `wasm-pack test --headless --firefox` (or `--chrome`) inside the crate directory
- **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.