npm package: @hauska-sdk/wallet
Description: CNS Protocol Wallet SDK - Secure wallet management and signing
Author: Hauska SDK Team
Latest version: 0.1.0

# @hauska-sdk/wallet

Secure wallet management and signing for the CNS Protocol SDK.

## Features

- ✅ **Automatic Wallet Creation** - Generate new Ethereum wallets
- ✅ **Secure Encryption** - AES-256-GCM encryption with PBKDF2 key derivation
- ✅ **Import/Export** - Encrypted wallet backup and restore
- ✅ **Message Signing** - EIP-191 and EIP-712 signature support
- ✅ **Seed Phrase Support** - Create wallets from mnemonic phrases
- ✅ **Password Protection** - All wallets encrypted with user passwords

## Installation

```bash
npm install @hauska-sdk/wallet
```

## Quick Start

```typescript
import { WalletManager } from '@hauska-sdk/wallet';

const manager = new WalletManager();

// Create a new wallet
const wallet = await manager.createWallet({
  password: 'user-password-123',
  userId: 'user-123',
});

console.log('Wallet address:', wallet.address);

// Sign a message
const signature = await manager.signMessage(
  wallet.address,
  'Hello, World!',
  'user-password-123'
);

// Export wallet for backup
const exported = await manager.exportWallet(
  wallet.address,
  'user-password-123'
);

// Import wallet later
const imported = await manager.importWallet({
  encryptedJson: exported,
  password: 'user-password-123',
});
```

## API Reference

### WalletManager

#### `createWallet(options)`

Create a new wallet.

```typescript
const wallet = await manager.createWallet({
  password: 'user-password',
  userId: 'user-123', // optional
});
```

#### `getOrCreateWallet(userId, password)`

Get existing wallet or create new one for user.

```typescript
const wallet = await manager.getOrCreateWallet('user-123', 'password');
```

#### `exportWallet(address, password)`

Export wallet as encrypted JSON.

```typescript
const exported = await manager.exportWallet(wallet.address, 'password');
```

#### `importWallet(options)`

Import wallet from encrypted JSON.

```typescript
const wallet = await manager.importWallet({
  encryptedJson: exportedJson,
  password: 'password',
  userId: 'user-123', // optional
});
```

#### `signMessage(address, message, password)`

Sign a message (EIP-191).

```typescript
const signature = await manager.signMessage(
  wallet.address,
  'Hello, World!',
  'password'
);
```

#### `signTypedData(address, domain, types, value, password)`

Sign typed data (EIP-712).

```typescript
const signature = await manager.signTypedData(
  wallet.address,
  {
    name: 'MyApp',
    version: '1',
    chainId: 8453, // Base
  },
  {
    Message: [{ name: 'content', type: 'string' }],
  },
  { content: 'Hello' },
  'password'
);
```

#### `createWalletFromSeedPhrase(mnemonic, password, userId?, accountIndex?)`

Create wallet from BIP39 mnemonic.

```typescript
const wallet = await manager.createWalletFromSeedPhrase(
  'abandon abandon abandon...',
  'password',
  'user-123',
  0 // account index
);
```

#### `verifyPassword(address, password)`

Verify wallet password without decrypting.

```typescript
const isValid = await manager.verifyPassword(wallet.address, 'password');
```

## Security

### Encryption

- **Algorithm:** AES-256-GCM
- **Key Derivation:** PBKDF2 with 100,000+ iterations
- **Salt:** Unique 32-byte salt per wallet
- **IV:** Unique 16-byte IV per encryption

### Best Practices

1. **Never store plaintext private keys**
2. **Use strong passwords** (minimum 12 characters)
3. **Store encrypted wallets securely**
4. **Backup wallets** using export functionality
5. **Verify passwords** before operations

## Storage

The WalletManager currently stores wallets in memory. In production, you should:

1. Store encrypted wallets in a database
2. Use secure key management
3. Implement proper access controls
4. Add audit logging

## Testing

```bash
npm test
```

## License

MIT