ETH Shamir

A TypeScript command-line tool for creating and restoring Ethereum private keys and mnemonics using Shamir's Secret Sharing scheme with comprehensive testing and CI/CD support.

Features

• 🔐 Secure Secret Sharing: Split Ethereum private keys and mnemonics into multiple shares
• 🔑 Key Restoration: Restore private keys and mnemonics from a threshold number of shares
• ✅ Share Validation: Validate shares without revealing the secret
• 🎯 Flexible Thresholds: Configure total shares and minimum threshold
• 📁 File Support: Save/load shares from files
• 📄 PDF Generation: Generate PDF documents with QR codes for each share
• 🖥️ Interactive Mode: User-friendly command-line interface
• 🌱 Mnemonic Generation: Generate new mnemonics with viem and create shares automatically
• 🔒 Password Protection: Optional AES256 encryption for additional security
• 🧪 Comprehensive Testing: Full test suite with unit, E2E, and performance tests
• 🚀 CI/CD Ready: GitHub Actions workflow for automated testing and deployment

Installation

Option 1: Install as Global Package (Recommended)

# Install globally from npm
npm install -g eth-shamir

# Verify installation
eth-shamir --help

Option 2: Install from Source

# Clone the repository
git clone https://github.com/turinglabsorg/eth-shamir
cd eth-shamir

# Install dependencies
npm install

# Build the project
npm run build

# Use locally
npm run dev -- <command>

Usage

Create Shares

Split an Ethereum private key into multiple shares:

# Interactive mode
eth-shamir create

# Command line mode
eth-shamir create --key <private-key> --shares 5 --threshold 3

# Save shares to file
eth-shamir create --key <private-key> --shares 5 --threshold 3 --output shares.txt

# With password protection
eth-shamir create --key <private-key> --shares 5 --threshold 3 --password "mypassword"

# Generate PDF documents with QR codes
eth-shamir create --key <private-key> --shares 5 --threshold 3 --pdf

# Generate PDF documents with custom output directory
eth-shamir create --key <private-key> --shares 5 --threshold 3 --pdf --pdf-output my-shares

Restore Private Key

Restore a private key from shares:

# Interactive mode
eth-shamir restore

# From command line arguments
eth-shamir restore --shares <share1> <share2> <share3>

# From file
eth-shamir restore --file shares.txt

# With password protection
eth-shamir restore --shares <share1> <share2> <share3> --password "mypassword"

Validate Shares

Validate shares without restoring the secret:

# Interactive mode
eth-shamir validate

# From command line arguments
eth-shamir validate --shares <share1> <share2> <share3>

# From file
eth-shamir validate --file shares.txt

# With password protection
eth-shamir validate --shares <share1> <share2> <share3> --password "mypassword"

Generate Mnemonic and Shares

Generate a new mnemonic and automatically create shares:

# Interactive mode
eth-shamir generate

# Command line mode
eth-shamir generate --shares 5 --threshold 3

# Save to file
eth-shamir generate --shares 5 --threshold 3 --output mnemonic-shares.txt

# With password protection
eth-shamir generate --shares 5 --threshold 3 --password "mypassword"

# Generate PDF documents with QR codes
eth-shamir generate --shares 5 --threshold 3 --pdf

# Generate PDF documents with custom output directory
eth-shamir generate --shares 5 --threshold 3 --pdf --pdf-output my-mnemonic-shares

PDF Generation Feature

The PDF generation feature creates professional, print-ready documents for each share with the following features:

PDF Document Contents

• Header: Document title, share information, and threshold requirements
• QR Code: Large, scannable QR code containing the share data
• Instructions: Step-by-step instructions for using the share
• Security Warning: Prominent warning about document security
• Share Information: Share number, total shares, and truncated share data

Benefits of PDF Shares

• Physical Storage: Print and store shares in secure physical locations
• Easy Scanning: Large QR codes for quick restoration
• Professional Format: Clean, organized layout suitable for important documents
• Security: Clear warnings and instructions for proper handling
• Backup: Physical backup of digital shares

PDF File Naming

PDF files are automatically named with the following pattern:

{title}-{share-number}-of-{total-shares}-{date}.pdf

Examples:

• ethereum-private-key-share-01-of-5-2025-09-08.pdf
• ethereum-mnemonic-share-02-of-3-2025-09-08.pdf

Security Considerations

• Each PDF contains only one share
• QR codes contain the complete share data
• Documents include security warnings
• Store PDFs in separate, secure locations
• Consider laminating for durability

Command Options

Create Command

• -k, --key <privateKey>: Ethereum private key (64 hex characters, with or without 0x prefix)
• -n, --shares <number>: Total number of shares to create (default: 5)
• -t, --threshold <number>: Minimum shares required to restore (default: 3)
• -o, --output <file>: Output file for shares (optional)
• -p, --password <password>: Password to encrypt shares (optional)
• --pdf: Generate PDF documents with QR codes for each share
• --pdf-output <directory>: Directory to save PDF files (default: shares-pdf)

Restore Command

• -s, --shares <shares...>: Share strings to use for restoration
• -f, --file <file>: File containing shares (one per line)
• -p, --password <password>: Password to decrypt shares (optional)

Validate Command

• -s, --shares <shares...>: Share strings to validate
• -f, --file <file>: File containing shares (one per line)
• -p, --password <password>: Password to decrypt shares (optional)

Generate Command

• -n, --shares <number>: Total number of shares to create (default: 5)
• -t, --threshold <number>: Minimum shares required to restore (default: 3)
• -o, --output <file>: Output file for mnemonic and shares (optional)
• -p, --password <password>: Password to encrypt shares (optional)
• --pdf: Generate PDF documents with QR codes for each share
• --pdf-output <directory>: Directory to save PDF files (default: mnemonic-shares-pdf)

Examples

Example 1: Create 5 shares with threshold 3

# With 0x prefix
eth-shamir create --key 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef --shares 5 --threshold 3

# Without 0x prefix (also works)
eth-shamir create --key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef --shares 5 --threshold 3

Example 2: Restore from 3 shares

eth-shamir restore --shares 01a1b2c3d4e5f6... 02f6e5d4c3b2a1... 03b2a1c3d4e5f6...

Example 3: Save shares to file and restore from file

# Create and save shares (with 0x prefix)
eth-shamir create --key 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef --output my-shares.txt

# Restore from file
eth-shamir restore --file my-shares.txt

Example 4: Generate new mnemonic and create shares

# Generate mnemonic and create 5 shares with threshold 3
eth-shamir generate --shares 5 --threshold 3

# Generate and save to file
eth-shamir generate --shares 3 --threshold 2 --output my-mnemonic.txt

Example 5: Password Protection

# Create encrypted shares
eth-shamir create --key 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef --shares 3 --threshold 2 --password "securepassword"

# Restore with password
eth-shamir restore --shares <encrypted-share1> <encrypted-share2> --password "securepassword"

# Generate encrypted mnemonic shares
eth-shamir generate --shares 3 --threshold 2 --password "securepassword"

Password Protection

The tool supports optional AES256 password protection for enhanced security:

How it Works

1. Secret Encryption: If a password is provided, the original secret (private key or mnemonic) is encrypted using AES256
2. Share Creation: The encrypted secret is then split into shares using Shamir's Secret Sharing
3. Share Encryption: Each share is individually encrypted with the same password
4. Double Protection: This provides two layers of security - the secret is encrypted, and the shares are also encrypted

Security Benefits

• Defense in Depth: Multiple layers of encryption
• Share Security: Even if individual shares are compromised, they're encrypted
• Secret Security: The original secret is encrypted before being split
• Password Separation: Keep your password separate from your shares

Usage Notes

• Password Required: You must provide the same password when restoring encrypted shares
• Password Security: Choose a strong, unique password and store it securely
• No Recovery: If you lose the password, the shares cannot be decrypted
• Optional Feature: Password protection is optional - you can use the tool without it

Testing

This project includes a comprehensive test suite with multiple test types:

Test Types

• Unit Tests: Test individual components and utilities
• E2E Tests: Test complete CLI workflows and user interactions
• Performance Tests: Test performance and memory usage under load

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:e2e           # End-to-end tests only
npm run test:performance   # Performance tests only
npm run test:all           # All tests

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

# Run in CI mode
npm run test:ci

# Use custom test runner
node scripts/test.js [test-type]

Test Structure

tests/
├── unit/                 # Unit tests
│   └── shamir.test.ts   # Core functionality tests
├── e2e/                 # End-to-end tests
│   └── cli.test.ts      # CLI workflow tests
├── performance/         # Performance tests
│   └── performance.test.ts
├── helpers/             # Test utilities
│   └── test-utils.ts    # Test helper functions
├── fixtures/            # Test data and files
└── setup.ts            # Test setup configuration

Development

Available Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run dev: Run in development mode with ts-node
• npm start: Run the compiled JavaScript
• npm run clean: Clean build artifacts
• npm test: Run all tests
• npm run test:unit: Run unit tests only
• npm run test:e2e: Run E2E tests only
• npm run test:performance: Run performance tests only
• npm run test:coverage: Run tests with coverage report
• npm run test:watch: Run tests in watch mode
• npm run test:ci: Run tests in CI mode
• npm run lint: Run ESLint
• npm run lint:fix: Fix ESLint issues

Project Structure

src/
├── index.ts              # Main CLI entry point
├── commands/             # Command implementations
│   ├── create.ts         # Create shares command
│   ├── restore.ts        # Restore key command
│   ├── validate.ts       # Validate shares command
│   └── generate.ts       # Generate mnemonic command
└── utils/                # Utility functions
    ├── shamir.ts         # Shamir's Secret Sharing implementation
    └── encryption.ts     # AES256 encryption utilities
    └── pdf.ts            # PDF generation utilities

tests/                    # Test suite
├── unit/                 # Unit tests
├── e2e/                  # End-to-end tests
├── performance/          # Performance tests
├── helpers/              # Test utilities
└── fixtures/             # Test data

.github/
└── workflows/
    └── ci.yml           # CI/CD pipeline

CI/CD Pipeline

The project includes a GitHub Actions workflow (.github/workflows/ci.yml) that:

• Runs tests on multiple Node.js versions (18.x, 20.x)
• Performs security audits
• Generates coverage reports
• Builds and tests the CLI package
• Automatically publishes to npm on main branch pushes

Code Quality

• ESLint: Code linting with TypeScript support
• Jest: Testing framework with coverage reporting
• TypeScript: Strong typing and compile-time error checking
• Prettier: Code formatting (if configured)

Security Considerations

⚠️ Important Security Notes:

1. Private Key Security: Never share your private key with anyone
2. Share Distribution: Store shares in different secure locations
3. Threshold Management: Choose appropriate threshold values
4. Share Destruction: Consider destroying shares after use
5. Environment Security: Run in secure environments only
6. Password Security: Use strong, unique passwords for encryption
7. Password Storage: Store passwords separately from shares
8. Backup Strategy: Have secure backup strategies for both shares and passwords

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the test suite: npm test
6. Ensure all tests pass: npm run test:ci
7. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Write tests for new features
• Update documentation as needed
• Ensure CI/CD pipeline passes
• Follow semantic versioning for releases