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

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 for complete usage examples.

Basic usage:

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:

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

WASM Initialization: Always call await init() before using any other functions
MIME Types: The demo requires a server that properly serves WASM files
Browser Compatibility: Requires modern browsers with WebAssembly support
Module Loading: Uses ES modules - ensure your build system supports them