ndwallet-core/pkg/README.md

Core cryptographic library for NDWallet browser environments

# NDWallet Core

A WebAssembly-based core library for cryptographic operations in browser environments. This library provides high-performance cryptographic primitives for key derivation, encryption/decryption, secret sharing, and seed phrase management.

## Features

- **WebAuthn Integration**: Seamless integration with the WebAuthn API for passkey-based authentication
- **PRF Extension Support**: Use the WebAuthn PRF extension for more secure key derivation
- **Key Derivation**: Derive cryptographic keys from WebAuthn responses
- **Encryption/Decryption**: AES-GCM encryption for secure data storage
- **Secret Sharing**: Shamir's Secret Sharing for distributing secrets across multiple locations
- **Seed Phrase Management**: BIP39 seed phrase generation, validation, and conversion
- **Wallet Module**: High-level wallet creation and management functions
- **WASM Performance**: Near-native performance for cryptographic operations

## Installation

```bash
npm install ndwallet-core
```

## Prerequisites

To build this library, you'll need:

1. Rust and Cargo (https://rustup.rs/)
2. wasm-pack (https://rustwasm.github.io/wasm-pack/installer/)
3. Node.js and npm

## Building

```bash
# Build the WASM module and TypeScript wrapper
npm run build
```

## Usage

### Core Cryptographic Functions

```typescript
import { ndWalletCore, LOCAL_SHARE_ENCRYPTION_CONTEXT } from 'ndwallet-core';

// Start WebAuthn registration with PRF extension
async function register() {
  // Get registration options from your server
  let options = await fetchRegistrationOptionsFromServer();
  
  // Add PRF extension to options
  options = ndWalletCore.addPrfExtensionToRegistrationOptions(options);
  
  // Start WebAuthn registration
  const response = await ndWalletCore.startRegistration(options);
  
  // Derive a master key from the PRF output
  const masterKey = ndWalletCore.deriveMasterKeyFromPrf(response);
  
  // Derive an encryption key for a specific context
  const encryptionKey = ndWalletCore.deriveEncryptionKey(masterKey, LOCAL_SHARE_ENCRYPTION_CONTEXT);
  
  // Generate a seed phrase
  const seedPhrase = ndWalletCore.generateSeedPhrase();
  
  // Split the seed phrase into shares (2 of 3 threshold)
  const shares = ndWalletCore.splitSecret(seedPhrase, 2, 3);
  
  // Encrypt a share
  const encryptedShare = ndWalletCore.encryptData(shares[0], encryptionKey);
  
  // Send the registration response and other data to your server
  await sendToServer(response, encryptedShare);
}

// Start WebAuthn authentication with PRF extension
async function authenticate() {
  // Get authentication options from your server
  let options = await fetchAuthenticationOptionsFromServer();
  
  // Get the PRF salt from your server
  const prfSalt = await getPrfSaltFromServer();
  
  // Add PRF extension to options
  options = ndWalletCore.addPrfExtensionToAuthenticationOptions(options, prfSalt);
  
  // Start WebAuthn authentication
  const response = await ndWalletCore.startAuthentication(options);
  
  // Derive a master key from the PRF output
  const masterKey = ndWalletCore.deriveMasterKeyFromPrf(response);
  
  // Derive an encryption key for a specific context
  const encryptionKey = ndWalletCore.deriveEncryptionKey(masterKey, LOCAL_SHARE_ENCRYPTION_CONTEXT);
  
  // Get encrypted share from localStorage or server
  const encryptedShare = getEncryptedShare();
  
  // Decrypt the share
  const share = ndWalletCore.decryptData(encryptedShare, encryptionKey);
  
  // Send the authentication response to your server
  await sendToServer(response);
}

### Wallet Module

```javascript
import {
  generateSeedPhrase,
  createWallet,
  restoreFromBackup,
  getAddress,
  recoverSeedPhrase
} from 'ndwallet-core';

// Generate a new seed phrase
const seedPhrase = generateSeedPhrase();

// Create a wallet
const wallet = await createWallet({
  seedPhrase,
  network: 'ethereum',
  accountIndex: 0,
  storage: {
    storeLocally: true,
    storeOnServer: true,
    createBackup: true
  }
});

console.log('Wallet address:', wallet.address);

// Get address for different network/account
const btcAddress = getAddress(wallet, 'bitcoin', 0);
```

See the [Wallet Module README](./js/wallet/README.md) for more details.

## API Reference

### Constants

- `LOCAL_SHARE_ENCRYPTION_CONTEXT`: Context for local share encryption
- `SERVER_SHARE_ENCRYPTION_CONTEXT`: Context for server share encryption
- `BACKUP_SHARE_ENCRYPTION_CONTEXT`: Context for backup share encryption

### WebAuthn API

- `startRegistration(options)`: Start WebAuthn registration with PRF extension
- `startAuthentication(options)`: Start WebAuthn authentication with PRF extension
- `addPrfExtensionToRegistrationOptions(options, prfSalt)`: Add PRF extension to registration options
- `addPrfExtensionToAuthenticationOptions(options, prfSalt)`: Add PRF extension to authentication options
- `generate_prf_salt()`: Generate a random PRF salt
- `create_prf_extension(salt)`: Create a PRF extension input for WebAuthn
- `extract_prf_from_response(response)`: Extract PRF output from WebAuthn response

### Key Derivation

- `deriveMasterKeyFromPrf(response)`: Derive a master key from a WebAuthn response using PRF extension
- `derive_encryption_key(masterKey, context)`: Derive an encryption key from a master key and context
- `deriveEncryptionKey(masterKey, context)`: High-level wrapper for derive_encryption_key

### Encryption/Decryption

- `encrypt_data(data, key)`: Encrypt data using AES-GCM
- `encryptData(data, key)`: High-level wrapper for encrypt_data
- `decrypt_data(encryptedData, key)`: Decrypt data using AES-GCM
- `decryptData(encryptedData, key)`: High-level wrapper for decrypt_data

### Seed Phrase Management

- `generate_seed_phrase()`: Generate a random BIP39 seed phrase
- `generateSeedPhrase()`: High-level wrapper for generate_seed_phrase
- `seed_phrase_to_seed(seedPhrase)`: Convert a BIP39 seed phrase to a seed
- `seedPhraseToSeed(seedPhrase)`: High-level wrapper for seed_phrase_to_seed

### Secret Sharing

- `split_secret(secret, threshold, shares)`: Split a secret into shares using Shamir's Secret Sharing
- `splitSecret(secret, threshold, shares)`: High-level wrapper for split_secret
- `combine_shares(shares)`: Combine shares to reconstruct a secret
- `combineShares(shares)`: High-level wrapper for combine_shares

## License

MIT