Tommy Verrall
3e8451f292
- keep all the internal-dev wasm pieces as future examples - everything previously was going to be removed - shows functioning wasm interaction with the js
126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# Nym Browser Extension Storage
|
|
|
|
A WebAssembly-based storage component for securely managing mnemonics in extensions. This component provides encrypted storage functionality using IndexedDB with password-based encryption.
|
|
|
|
## Overview
|
|
|
|
This storage component is built in Rust and compiled to WebAssembly, providing:
|
|
|
|
- **Secure mnemonic storage**: Password-encrypted storage of BIP39 mnemonics
|
|
- **IndexedDB integration**: Browser-native persistent storage
|
|
- **Multiple account support**: Store and manage multiple mnemonic phrases with custom names
|
|
- **Type-safe API**: Promise-based JavaScript API with proper error handling
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Rust (latest stable)
|
|
- `wasm-pack` tool for building WebAssembly
|
|
- Node.js (for the demo server)
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cd storage
|
|
make wasm-pack
|
|
```
|
|
|
|
This will compile the Rust code to WebAssembly and generate the necessary JavaScript bindings.
|
|
|
|
### Example Usage
|
|
|
|
See the [internal-dev example](./storage/internal-dev/index.js) for complete usage examples.
|
|
|
|
Basic usage:
|
|
|
|
```javascript
|
|
import init, { ExtensionStorage, set_panic_hook } from "@nymproject/extension-storage"
|
|
|
|
// Initialize the WASM module first
|
|
await init();
|
|
|
|
// Set up better error handling
|
|
set_panic_hook();
|
|
|
|
// Create storage instance with password
|
|
const storage = await new ExtensionStorage("your-secure-password");
|
|
|
|
// Store a mnemonic
|
|
const mnemonic = "your twenty four word mnemonic phrase goes here...";
|
|
await storage.store_mnemonic("my-wallet", mnemonic);
|
|
|
|
// Read a mnemonic
|
|
const retrievedMnemonic = await storage.read_mnemonic("my-wallet");
|
|
|
|
// Check if a mnemonic exists
|
|
const exists = await storage.has_mnemonic("my-wallet");
|
|
|
|
// Get all stored mnemonic keys
|
|
const allKeys = await storage.get_all_mnemonic_keys();
|
|
|
|
// Remove a mnemonic
|
|
await storage.remove_mnemonic("my-wallet");
|
|
```
|
|
|
|
## Development
|
|
|
|
To run the internal development example:
|
|
|
|
```bash
|
|
cd storage
|
|
|
|
make demo
|
|
|
|
# Option 2: Manual server setup
|
|
cd internal-dev && node serve.js
|
|
|
|
# Then open http://localhost:8000 in your browser
|
|
```
|
|
|
|
**Note**: The demo requires a server that properly serves WASM files with `application/wasm` MIME type. The Node.js server is recommended as it handles MIME types more reliably.
|
|
|
|
## API Reference
|
|
|
|
### Initialization
|
|
- `init()` - **Required**: Initialize the WASM module before using other functions
|
|
|
|
### Constructor
|
|
- `new ExtensionStorage(password: string)` - Creates a new storage instance with the given password
|
|
|
|
### Static Methods
|
|
- `ExtensionStorage.exists()` - Check if storage database exists
|
|
|
|
### Instance Methods
|
|
- `store_mnemonic(name: string, mnemonic: string)` - Store a mnemonic with the given name
|
|
- `read_mnemonic(name: string)` - Retrieve a mnemonic by name (returns null if not found)
|
|
- `has_mnemonic(name: string)` - Check if a mnemonic with the given name exists
|
|
- `get_all_mnemonic_keys()` - Get all stored mnemonic names
|
|
- `remove_mnemonic(name: string)` - Remove a mnemonic by name
|
|
|
|
### Error Handling
|
|
- `set_panic_hook()` - Set up better stack traces for Rust panics in development
|
|
|
|
## Security Features
|
|
|
|
- **Password-based encryption**: All data is encrypted using the provided password
|
|
- **BIP39 validation**: Mnemonics are validated before storage
|
|
- **Secure memory handling**: Sensitive data is zeroed from memory when no longer needed
|
|
- **Browser sandbox**: Runs within the browser's security model
|
|
|
|
## Architecture
|
|
|
|
The storage component consists of:
|
|
|
|
- **Rust core** (`src/storage.rs`): Main storage implementation with encryption
|
|
- **WASM bindings** (`src/lib.rs`): WebAssembly interface layer
|
|
- **Error handling** (`src/error.rs`): Comprehensive error types
|
|
- **Build configuration** (`Cargo.toml`, `Makefile`): Build and dependency management
|
|
|
|
## Important Notes
|
|
|
|
1. **WASM Initialization**: Always call `await init()` before using any other functions
|
|
2. **MIME Types**: The demo requires a server that properly serves WASM files
|
|
3. **Browser Compatibility**: Requires modern browsers with WebAssembly support
|
|
4. **Module Loading**: Uses ES modules - ensure your build system supports them
|