235 lines
8.8 KiB
Markdown
235 lines
8.8 KiB
Markdown
# Modular Rust System: Key-Value Store, Vault, and EVM Client
|
|
|
|
A modular, async, and cross-platform cryptographic stack in Rust. Built for both native (desktop/server) and WASM (browser) environments, this system provides secure storage, cryptographic operations, and Ethereum (EVM) client functionality—all with a focus on extensibility, testability, and scripting.
|
|
|
|
## Crate Overview
|
|
|
|
- **kvstore/**: Async key-value store trait and implementations (native: `sled`, WASM: IndexedDB)
|
|
- **vault/**: Cryptographic vault for encrypted keyspaces, key management, and signing; uses `kvstore` for persistence
|
|
- **evm_client/**: Async EVM RPC client, integrates with `vault` for secure signing; supports trait-based signers and modular providers
|
|
- **cli_app/** _(planned)_: Command-line interface for scripting, automation, and Rhai scripting
|
|
- **web_app/** _(planned)_: WASM web app exposing APIs to JavaScript/browser scripting
|
|
- **wasm/** _(planned)_: WebAssembly module for browser/extension integration
|
|
- **browser_extension/** _(planned)_: Browser extension for secure scripting and automation
|
|
- **rhai scripting** _(planned)_: Unified scripting API for both CLI and browser (see [`docs/rhai_architecture_plan.md`](docs/rhai_architecture_plan.md))
|
|
|
|
---
|
|
|
|
## What is Rust Conditional Compilation?
|
|
|
|
Rust's conditional compilation allows you to write code that only gets included for certain platforms or configurations. This is done using attributes like `#[cfg(target_arch = "wasm32")]` for WebAssembly, or `#[cfg(not(target_arch = "wasm32"))]` for native platforms. It enables a single codebase to support multiple targets (such as desktop and browser) with platform-specific logic where needed.
|
|
|
|
**Example:**
|
|
```rust
|
|
#[cfg(target_arch = "wasm32")]
|
|
// This code only compiles for WebAssembly targets
|
|
```
|
|
|
|
## What is WASM (WebAssembly)?
|
|
|
|
WebAssembly (WASM) is a binary instruction format for a stack-based virtual machine. It allows code written in languages like Rust, C, or C++ to run at near-native speed in web browsers and other environments. In this project, WASM enables the cryptographic vault to work securely inside the browser, exposing Rust functions to JavaScript and web applications.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
> **Note:** Some directories are planned for future extensibility and scripting, and may not exist yet in the current workspace.
|
|
|
|
```
|
|
.
|
|
├── kvstore/ # Key-value store trait and backends
|
|
├── vault/ # Cryptographic vault (shared core)
|
|
├── evm_client/ # EVM RPC client (shared core)
|
|
├── cli_app/ # Command-line tool for Rhai scripts (planned)
|
|
├── web_app/ # WASM web app exposing APIs (planned)
|
|
├── wasm/ # WebAssembly module for browser/extension (planned)
|
|
├── browser_extension/ # Extension source (planned)
|
|
├── docs/ # Architecture & usage docs
|
|
└── README.md
|
|
```
|
|
|
|
## Architecture Highlights
|
|
- **Modular and async:** All APIs are async and runtime-agnostic (works with both native and WASM targets)
|
|
- **Conditional backends:** Uses Cargo features and `cfg` for platform-specific storage/networking
|
|
- **Secure by design:** Vault encrypts all key material at rest using modern cryptography
|
|
- **Extensible:** Trait-based APIs for signers and providers, ready for scripting and new integrations
|
|
- **Tested everywhere:** Native and browser (WASM) backends are covered by automated tests and a unified Makefile
|
|
|
|
---
|
|
|
|
## Conditional Compilation & WASM Support
|
|
|
|
This project makes extensive use of Rust's conditional compilation to support both native and WebAssembly (WASM) environments with a single codebase. Key points:
|
|
|
|
- **Platform-specific code:**
|
|
- Rust's `#[cfg(target_arch = "wasm32")]` attribute is used to write WASM-specific code, while `#[cfg(not(target_arch = "wasm32"))]` is for native targets.
|
|
- This pattern is used for struct definitions, method implementations, and even module imports.
|
|
|
|
- **Example: SessionManager**
|
|
```rust
|
|
#[cfg(not(target_arch = "wasm32"))]
|
|
pub struct SessionManager<S: KVStore + Send + Sync> { ... }
|
|
|
|
#[cfg(target_arch = "wasm32")]
|
|
pub struct SessionManager<S: KVStore> { ... }
|
|
```
|
|
|
|
- **WASM Bindings:**
|
|
- The `wasm_app` crate uses `wasm-bindgen` to expose Rust functions to JavaScript, enabling browser integration.
|
|
- Functions are annotated with `#[wasm_bindgen]` and exported for use in JS/TS.
|
|
|
|
- **Storage Backends:**
|
|
- Native uses `sled` or other file-based stores.
|
|
- WASM uses IndexedDB (via `kvstore::wasm::WasmStore`).
|
|
|
|
- **Building for WASM:**
|
|
- Use `wasm-pack build --target web` to build the WASM package.
|
|
- Serve the resulting files with a static server for browser use.
|
|
|
|
- **Testing:**
|
|
- Both native and WASM tests are supported. WASM tests can be run in headless browsers using `wasm-pack test --headless --firefox` or similar commands.
|
|
|
|
---
|
|
|
|
## Building and Testing
|
|
|
|
### Prerequisites
|
|
- Rust (latest stable recommended)
|
|
- wasm-pack (for browser tests)
|
|
- Firefox or Chrome (for browser testing)
|
|
|
|
### Native Build & Test
|
|
```sh
|
|
cargo build
|
|
cargo test
|
|
```
|
|
|
|
### Browser (WASM) Tests
|
|
Run all browser tests for all modules:
|
|
```sh
|
|
make test-browser-all
|
|
```
|
|
Or run for a specific module:
|
|
```sh
|
|
make test-browser-kvstore
|
|
make test-browser-vault
|
|
make test-browser-evm-client
|
|
```
|
|
Set `BROWSER=chrome` to use Chrome instead of Firefox.
|
|
|
|
## Scripting & Extensibility
|
|
- **Rhai scripting**: The architecture is ready for ergonomic scripting via Rhai, both in CLI and browser (see [`docs/rhai_architecture_plan.md`](docs/rhai_architecture_plan.md))
|
|
- **Browser extension**: Planned support for browser extension scripting and secure key usage
|
|
|
|
## Documentation
|
|
- [Architecture Overview](docs/architecture.md)
|
|
- [EVM Client Plan](docs/evm_client_architecture_plan.md)
|
|
- [Rhai Scripting Plan](docs/rhai_architecture_plan.md)
|
|
|
|
---
|
|
|
|
For questions, contributions, or more details, see the architecture docs or open an issue!
|
|
|
|
- Rust (latest stable recommended)
|
|
- For WASM: `wasm-pack`, Firefox or Chrome (for browser tests)
|
|
|
|
### Native
|
|
```sh
|
|
cargo check --workspace --features kvstore/native
|
|
```
|
|
|
|
### WASM (kvstore only)
|
|
```sh
|
|
cd kvstore
|
|
wasm-pack test --headless --firefox --features web
|
|
```
|
|
|
|
# Rhai Scripting System
|
|
|
|
A unified system for writing and executing [Rhai](https://rhai.rs/) scripts, powered by shared Rust core logic. Supports both local CLI execution and secure browser extension use, with the same business logic compiled to WebAssembly.
|
|
|
|
---
|
|
|
|
## Project Goals
|
|
- **Write and run Rhai scripts** both locally (CLI) and in the browser (extension).
|
|
- **Reuse the same Rust core logic** (vault, evm_client) across all platforms.
|
|
- **Sandboxed, secure script execution** in both native and WASM environments.
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
- **Shared Rust Crates:**
|
|
- `vault/` and `evm_client/` implement business logic and expose APIs to Rhai.
|
|
- All logic is reusable in both native and WASM builds.
|
|
- **CLI Tool (`cli/`):**
|
|
- Runs Rhai scripts from files or stdin using the shared core.
|
|
- Outputs results to the terminal.
|
|
- **WebAssembly Module (`wasm/`):**
|
|
- Exposes `run_rhai(script: &str) -> String` via `wasm-bindgen`.
|
|
- Usable from browser JS and the extension.
|
|
- **Browser Extension (`browser_extension/`):**
|
|
- UI for entering and running Rhai scripts securely in the browser.
|
|
- Loads the WASM module and displays results.
|
|
- **Web App Integration:**
|
|
- Trusted web apps can send scripts to the extension for execution (via postMessage or WebSocket, with strict origin checks).
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### CLI
|
|
```
|
|
sal-cli run my_script.rhai
|
|
# or
|
|
cat my_script.rhai | sal-cli run
|
|
```
|
|
|
|
### Browser/Extension
|
|
- Enter Rhai code in the extension popup or trusted website.
|
|
- Extension loads the WASM module and calls `run_rhai(script)`.
|
|
- Result is displayed in the UI.
|
|
|
|
---
|
|
|
|
## Security
|
|
- All script execution is sandboxed via Rhai + WASM.
|
|
- Only accepts input from:
|
|
- Extension popup UI
|
|
- Approved websites (via content script)
|
|
- Trusted backend server (if using WebSocket)
|
|
- Strict origin and input validation.
|
|
- No internal APIs exposed beyond `run_rhai(script)`.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
```
|
|
.
|
|
├── kvstore/ # Key-value store trait and backends
|
|
├── vault/ # Cryptographic vault (shared core)
|
|
├── evm_client/ # EVM RPC client (shared core)
|
|
├── cli/ # Command-line tool for Rhai scripts
|
|
├── wasm/ # WebAssembly module for browser/extension
|
|
├── browser_extension/ # Extension source
|
|
├── docs/ # Architecture & usage docs
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
- [x] Unified async trait for key-value storage
|
|
- [x] Native and WASM backends for kvstore
|
|
- [x] Shared Rust core for vault and evm_client
|
|
- [ ] WASM module exposing `run_rhai`
|
|
- [ ] CLI tool for local Rhai script execution
|
|
- [ ] Browser extension for secure script execution
|
|
- [ ] Web app integration (postMessage/WebSocket)
|
|
- [ ] Full end-to-end integration and security review
|
|
|
|
---
|
|
|
|
## License
|
|
MIT OR Apache-2.0
|
|
|