BIC Signer Web Assembly

A secure WebAssembly-based cryptographic signing library for the BIC ecosystem. This package provides MPC (Multi-Party Computation) wallet functionality with enhanced security features including memory-safe sensitive data handling.

Features

• MPC Wallet: Multi-party computation wallet with Shamir Secret Sharing
• Secure Memory Handling: All sensitive data (private keys, passwords, recovery codes) are automatically zeroized on drop
• WASM-Native: Built for web browsers with optimal performance
• Ethereum Compatible: Full support for Ethereum account management and signing
• Type-Safe: Comprehensive type system with Rust's safety guarantees
• Web3 Ready: Integrates seamlessly with modern Web3 applications

Requirements

| Tool | Version | Purpose | |------|---------|---------| | Rust | 1.81.0+ | Core compilation | | Binaryen | 121+ | WASM optimization | | wasm-pack | latest | WASM build tool | | Node.js | 18+ | Development server | | Yarn | latest | Package management |

Setup

First-Time Setup

Install all required tools and dependencies:

make setup

This command will:

• Install Rust stable and nightly toolchains
• Add rustfmt and clippy components
• Install wasm-pack
• Install binaryen
• Install Node.js dependencies

Verify Installation

Check that all tools are properly installed:

make version

Expected output:

Rust:      rustc 1.81.0
Cargo:     cargo 1.81.0
Rustfmt:   rustfmt 1.7.0-nightly
Clippy:    clippy 0.1.81
wasm-pack: wasm-pack 0.12.1
Binaryen:  version 121
Node.js:   v18.x.x
Yarn:      1.22.x

Build

Production Build

Build optimized WebAssembly package:

yarn package

Architecture

Security Architecture

                            ┌─────────────────────────────────────────┐
                            │         JavaScript/TypeScript           │
                            │              Application                │
                            └─────────────┬───────────────────────────┘
                                          │ WASM Boundary
                            ┌─────────────▼───────────────────────────┐
                            │          Signer (lib.rs)                │
                            │  ┌────────────────────────────────────┐ │
                            │  │  Session Management                │ │
                            │  │  - startRequestSession()           │ │
                            │  │  - endRequestSession()             │ │
                            │  └────────────────────────────────────┘ │
                            │  ┌────────────────────────────────────┐ │
                            │  │  SensitiveString Wrapper           │ │
                            │  │  - Auto-zeroization on drop        │ │
                            │  │  - No plaintext copies             │ │
                            │  └────────────────────────────────────┘ │
                            └─────────────┬───────────────────────────┘
                                          │
                            ┌─────────────▼───────────────────────────┐
                            │      Core Wallet Operations             │
                            │  ┌──────────┐  ┌───────────────────┐    │
                            │  │   MPC    │  │  Shamir Secret    │    │
                            │  │  Wallet  │◄─┤  Sharing (SSS)    │    │
                            │  └────┬─────┘  └───────────────────┘    │
                            │       │                                 │
                            │  ┌────▼─────────────────────────────┐   │
                            │  │  Web Crypto & Encryption         │   │
                            │  │  - AES-256-GCM                   │   │
                            │  │  - ECDH key exchange             │   │
                            │  │  - Secure random generation      │   │
                            │  └──────────────────────────────────┘   │
                            │                                         │
                            │  ┌──────────────────────────────────┐   │
                            │  │  Account Management              │   │
                            │  │  - Ethereum signing              │   │
                            │  │  - Address derivation            │   │
                            │  │  - Key management                │   │
                            │  └──────────────────────────────────┘   │
                            └─────────────────────────────────────────┘

Data Flow: Wallet Creation

User Input (Password + Recovery Code)
    ↓
Generate Keypair
    ↓
Split into 3 Shares (Shamir's Secret Sharing)
    ├── Device Shard  → Encrypted with Password
    ├── Server Shard  → Sent to server
    └── Recovery Shard → Encrypted with Recovery Code
    ↓
Secure Transmission (RSA + AES-256-GCM)
    ↓
Server Storage

Security Features

1. Memory Safety

// All sensitive data wrapped in SensitiveString
pub struct SensitiveString(String);

impl Drop for SensitiveString {
    fn drop(&mut self) {
        unsafe {
            // Zeroize memory using write_volatile
            let bytes = self.0.as_bytes_mut();
            for byte in bytes.iter_mut() {
                core::ptr::write_volatile(byte, 0);
            }
        }
        self.0.clear();
    }
}

2. Zero-Copy Operations

// Direct reference access - no copies
let private_key: SensitiveString = reconstruct(shares)?;
let account = Account::new(private_key); // Consumes, no copy

3. Secure Key Exchange

// ECDH + AES-256-GCM for all server communication
encrypt_request(data, server_pubkey, client_pubkey)

Development

Code Quality

Format Code

make format

Lint Code

make lint

Testing

Unit Tests

Run Rust unit tests:

cargo test

Browser Testing

1. Run command:

wasm-pack test --{driver: chrome|firefox|....}

2. Open browser:

 http://127.0.0.1:8000

Example Testing

The test page provides:

• WASM module loading status
• Interactive function testing
• Real-time operation results
• Error handling demonstration

Usage

Installation

npm install @beincom/signer-wasm
# or
yarn add @beincom/signer-wasm
# or
pnpm add @beincom/signer-wasm

Basic Example

import { Signer } from '@beincom/signer-wasm';

// Initialize signer
const signer = new Signer();

// Start secure session
await signer.startRequestSession();

// Create wallet
const createRequest = {
  storeKey: 'user123',
  deviceId: 'device456',
  recoveryCode: 'word1 word2 word3 word4 word5 word6',
  password: 'SecurePassword123!',
  serverPublicKeyBase64: serverPubKey
};

const wallet = await signer.create(createRequest);
console.log('Wallet Address:', wallet.result.address);

// Authenticate
const authRequest = {
  deviceId: 'device456',
  password: 'SecurePassword123!',
  deviceShard: encryptedDeviceShard,
  data: securePayload
};

const account = await signer.authenticate(authRequest);
console.log('Authenticated:', account.address);

// Sign message
const signature = await account.signStringMessage('Hello World');
console.log('Signature:', signature);

// Clean up session
signer.endRequestSession();

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | invalid_private_key | Invalid key format | Ensure hex string is 64 chars | | Decryption failed | Wrong password | Verify password is correct | | Share id mismatch | Invalid shares | Use shares from same wallet | | Field requirement | Missing data | Check all required fields |

API Reference

Signer Class

Constructor

new Signer()

Methods

startRequestSession(): Promise<string>

Initialize a secure session with key pair generation.

endRequestSession(): void

Clean up session and zeroize sensitive data.

create(request: CreateWalletRequest): Promise<JsCarrier<CreateWalletResponse>>

Create a new MPC wallet.

authenticate(request: AuthRequest): Promise<Account>

Authenticate and reconstruct account.

resetPassword(request: ResetPasswordRequest): Promise<JsCarrier<ResetPasswordResponse>>

Reset password using recovery code.

changePassword(request: ChangePasswordRequest): Promise<JsCarrier<ChangePasswordResponse>>

Change password with current credentials.

retrieveRecoveryCode(request: RetrieveRecoveryCodeRequest): Promise<JsCarrier<string>>

Retrieve recovery code.

recovery(request: SetupForNewDeviceRequest): Promise<JsCarrier<string>>

Setup wallet on new device.

generateRecoveryCode(): Promise<JsCarrier<string>>

Generate BIP39 recovery code (6 words).

checkRecoveryCode(request: CheckRecoveryCodeRequest): Promise<JsCarrier<boolean>>

Validate recovery code.

Account Class

Methods

getAddress(): string

Get Ethereum address (0x...).

sign(hash: Uint8Array): Promise<string>

Sign a 32-byte hash.

signStringMessage(message: string): Promise<string>

Sign a UTF-8 string message.

signUint8ArrayMessage(message: Uint8Array): Promise<string>

Sign a byte array message.

Contributing

We welcome contributions! Please follow these guidelines:

Code Standards

• Follow Rust style guidelines (rustfmt)
• Pass all lints (clippy)
• Add tests for new features
• Update documentation
• Include security considerations

Commit Messages

Follow conventional commits:

feat: Add new wallet feature
fix: Resolve memory leak in zeroization
docs: Update API documentation
test: Add integration tests
chore: Update dependencies

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright (C) 2024 Beincom.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Community

• Chat: BIC Developer Chat
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Docs

Roadmap

• [ ] Hardware wallet integration
• [ ] Biometric authentication

Changelog

See CHANGELOG.md for version history and migration guides.

Made with ❤️ by the BIC Team