Sameh Abouelsaad cea2d7e655 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

3.5 KiB

Raw Blame History

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.

3.5 KiB Raw Blame History