# SSeed

[![PyPI Version](https://img.shields.io/pypi/v/sseed.svg)](https://pypi.org/project/sseed/)
[![CI Status](https://github.com/ethene/sseed/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/ethene/sseed/actions)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/sseed.svg)](https://pypi.org/project/sseed/)
[![Test Coverage](https://img.shields.io/badge/coverage-89.96%25-brightgreen.svg)](https://github.com/ethene/sseed)
[![Code Quality](https://img.shields.io/badge/pylint-9.86%2F10-brightgreen.svg)](https://github.com/ethene/sseed)

**Secure, offline BIP39/SLIP39 cryptocurrency seed management with multi-language support**

---

## ✨ Features

- 🌍 **Multi-Language BIP-39 Support** - Generate and restore mnemonics in 9 languages with automatic detection
- 🔐 **Generate secure BIP-39 mnemonics** with flexible word counts (12, 15, 18, 21, or 24 words) using cryptographically secure entropy
- 🌱 **Generate master seeds from mnemonics** using PBKDF2-HMAC-SHA512 per BIP-39 specification
- 🎯 **BIP85 deterministic entropy derivation** - unlimited child wallets, passwords, and keys from single master
- 🔄 **Split secrets using SLIP-39** with flexible group/threshold configurations
- 🔧 **Reconstruct mnemonics from shards** with integrity validation
- 🚫 **100% offline operation** - zero network calls, air-gapped security
- ⚡ **Lightning fast** - sub-millisecond operations, <100MB memory usage
- 🛡️ **Secure memory handling** - automatic cleanup of sensitive data
- 🧪 **Mathematical verification** - property-based testing with Hypothesis
- 🎯 **Simple CLI interface** - intuitive commands, version info, scriptable automation
- 📦 **Zero dependencies** - self-contained, easy deployment
- 🌍 **Cross-platform** - macOS, Linux, Windows compatibility

## 🌍 Multi-Language Support

SSeed supports all 9 official BIP-39 languages with automatic detection:

| Language | Code | Script | Example |
|----------|------|--------|---------|
| **English** | `en` | Latin | `abandon ability able...` |
| **Spanish** | `es` | Latin | `ábaco abdomen abedul...` |
| **French** | `fr` | Latin | `abaisser abandon abdiquer...` |
| **Italian** | `it` | Latin | `abaco abbaglio abbinare...` |
| **Portuguese** | `pt` | Latin | `abacate abalar abater...` |
| **Czech** | `cs` | Latin | `abdikace abeceda adresa...` |
| **Chinese (Simplified)** | `zh-cn` | Ideographic | `的 一 是 在 不 了...` |
| **Chinese (Traditional)** | `zh-tw` | Ideographic | `的 一 是 在 不 了...` |
| **Korean** | `ko` | Hangul | `가격 가끔 가난 가능...` |

### Language Features
- ✅ **Automatic Detection** - Identifies mnemonic language with 95%+ accuracy
- ✅ **Unicode Support** - Full support for international character sets
- ✅ **Generate in Any Language** - Use `--language/-l` flag for generation
- ✅ **Seamless Recovery** - Auto-detects language during restore operations
- ✅ **100% Backward Compatible** - English remains default, existing code unchanged

## ✨ Key Features

- **🔐 Secure Generation**: BIP-39 mnemonics with flexible word counts (12, 15, 18, 21, 24) using cryptographic entropy
- **🌍 Multi-Language**: Generate and restore in 9 languages with auto-detection
- **🎯 BIP85 Deterministic Entropy**: Generate unlimited child wallets, passwords, and hex entropy from one master seed
- **🧩 SLIP-39 Sharding**: Split mnemonics into threshold-based secret shares
- **🔄 Perfect Recovery**: Reconstruct original mnemonics from sufficient shards
- **🌱 Master Seed Generation**: BIP-39 compliant PBKDF2-HMAC-SHA512 seed derivation
- **🎯 BIP85 Deterministic Entropy**: Generate unlimited child wallets, passwords, and hex entropy from one master seed
- **🔍 Entropy Display**: View underlying entropy alongside mnemonics for verification
- **⚡ Cross-Tool Compatibility**: Full interoperability with official Trezor SLIP-39 CLI
- **🛡️ Security First**: Memory cleanup, input validation, and comprehensive error handling
- **📁 Flexible I/O**: File operations, stdin/stdout, and batch processing support
- **🧪 Battle Tested**: 632 comprehensive tests with 95%+ code coverage

## 🚀 Quick Install

```bash
pip install sseed
```

## 📖 Quick Start

### Generate → Shard → Restore Demo

```bash
# Generate a secure mnemonic (English by default)
$ sseed gen
abandon ability able about above absent absorb abstract absurd abuse access accident

# Generate in different languages
$ sseed gen -l es  # Spanish
ábaco abdomen abedul abeja abismo abogado abono aborto abrazo abrir absurdo abuelo

$ sseed gen -l zh-cn  # Chinese Simplified
的 一 是 在 不 了 有 和 人 这 中 大 为 上 个 国 我 以 要 他

# Generate master seed from mnemonic (BIP-39 → BIP-32 HD wallet seed)
$ sseed gen | sseed seed --hex
7adb1efaf1659636ca22a200c4e688a2041972ebb8d1d49a71c4cb40b4a283fc51d4cfe31d45c0f90eb08a246008f8707f961b674246b016aa303041ceccb848

# Split into 3-of-5 threshold shards (language auto-detected)
$ sseed gen -l es | sseed shard -g 3-of-5
# Language: Spanish (es) - Auto-detected
# Group 1 of 1 - Share 1 of 5: academic acid acrobat...
# Group 1 of 1 - Share 2 of 5: academic acid beard...
# Group 1 of 1 - Share 3 of 5: academic acid ceramic...
# Group 1 of 1 - Share 4 of 5: academic acid decision...
# Group 1 of 1 - Share 5 of 5: academic acid echo...

# Restore from any 3 shards (language auto-detected)
$ sseed restore shard1.txt shard2.txt shard3.txt
# Language: Spanish (es) - Auto-detected
ábaco abdomen abedul abeja abismo abogado abono aborto abrazo abrir absurdo abuelo
```

### System Information

```bash
# Show comprehensive version information
$ sseed version
🔐 SSeed v1.5.0
========================================

📋 Core Information:
   Version: 1.5.0
   Python:  3.12.2 (CPython)

🖥️  System Information:
   OS:           Darwin 23.6.0
   Architecture: arm64 (64bit)

📦 Dependencies:
   ✅ bip-utils: 2.9.3
   ✅ slip39: 13.1.0

# JSON format for automation
$ sseed version --json
{"sseed": "1.5.0", "python": "3.12.2", "platform": {...}}
```

### Advanced Usage

```bash
# Generate to file with timestamp
sseed gen -o "backup-$(date +%Y%m%d).txt"

# Generate 512-bit master seed from mnemonic (for HD wallets)
sseed seed -i mnemonic.txt --hex

# Generate master seed with passphrase (25th word protection)
sseed seed -i mnemonic.txt -p "my_passphrase" --hex

# Generate master seed with higher security (more PBKDF2 iterations)
sseed seed -i mnemonic.txt --iterations 4096 --hex

# Multi-group configuration (enterprise setup)
sseed shard -g "2:(2-of-3,3-of-5)" -i seed.txt --separate -o shards/

# Restore with passphrase protection
sseed restore -p "my-secure-passphrase" shard*.txt

# Generate with entropy display (for verification)
sseed gen --show-entropy

# Restore with entropy verification
sseed restore --show-entropy shard1.txt shard2.txt shard3.txt

# Entropy consistency verification workflow
ORIGINAL_ENTROPY=$(sseed gen --show-entropy | grep "# Entropy:" | cut -d' ' -f3)
echo "$ORIGINAL_ENTROPY" > entropy_backup.txt
```

## 🎯 BIP85 Deterministic Entropy

SSeed implements **BIP85** for deterministic entropy generation, enabling unlimited child wallets, passwords, and cryptographic secrets from a single master seed backup. This transforms SSeed into a complete cryptographic entropy management system.

### What is BIP85?

**BIP85** allows deriving multiple independent secrets from one master seed:
- **🔒 One Master Backup**: Single mnemonic protects unlimited child wallets
- **🎲 Deterministic**: Same parameters always produce identical output
- **🔐 Independent**: Child entropy appears completely random
- **🌍 Multi-Purpose**: BIP39 mnemonics, hex entropy, passwords
- **🛡️ Secure**: Information-theoretic independence between children

### Quick BIP85 Examples

```bash
# Generate master mnemonic
$ sseed gen -o master.txt

# Generate child BIP39 wallets
$ sseed bip85 bip39 -i master.txt -w 12 -n 0  # Child wallet #1
$ sseed bip85 bip39 -i master.txt -w 12 -n 1  # Child wallet #2
$ sseed bip85 bip39 -i master.txt -w 24 -l es -n 2  # Spanish child wallet

# Generate hex entropy (for keys, tokens)
$ sseed bip85 hex -i master.txt -b 32 -n 0    # 32 bytes entropy
$ sseed bip85 hex -i master.txt -b 16 -u -n 1 # 16 bytes uppercase

# Generate passwords 
$ sseed bip85 password -i master.txt -l 20 -c base64 -n 0      # Base64 password
$ sseed bip85 password -i master.txt -l 16 -c alphanumeric -n 1 # Alphanumeric
```

### BIP85 Applications

| Application | Purpose | Options | Example |
|-------------|---------|---------|---------|
| **bip39** | Child BIP39 mnemonics | 12/15/18/21/24 words, 9 languages | `sseed bip85 bip39 -w 12 -l en -n 0` |
| **hex** | Raw entropy bytes | 16-64 bytes, upper/lowercase | `sseed bip85 hex -b 32 -u -n 0` |
| **password** | Secure passwords | 4 character sets, 10-128 chars | `sseed bip85 password -l 20 -c base64 -n 0` |

### Advanced BIP85 Workflows

```bash
# Master → Multiple Child Wallets
sseed gen -o master.txt
sseed bip85 bip39 -i master.txt -w 12 -n 0 -o wallet1.txt  # Personal wallet
sseed bip85 bip39 -i master.txt -w 12 -n 1 -o wallet2.txt  # Business wallet  
sseed bip85 bip39 -i master.txt -w 12 -n 2 -o wallet3.txt  # Backup wallet

# Multi-Language Child Wallets
sseed bip85 bip39 -i master.txt -w 24 -l en -n 0 -o english.txt
sseed bip85 bip39 -i master.txt -w 24 -l es -n 1 -o spanish.txt
sseed bip85 bip39 -i master.txt -w 24 -l zh-cn -n 2 -o chinese.txt

# BIP85 + SLIP39 Combination  
sseed bip85 bip39 -i master.txt -w 12 -n 0 | sseed shard -g 3-of-5
sseed bip85 bip39 -i master.txt -w 24 -l es -n 1 | sseed shard -g 2-of-3

# Application-Specific Entropy
sseed bip85 hex -i master.txt -b 32 -n 0 -o app1_key.hex     # App 1 encryption key
sseed bip85 hex -i master.txt -b 32 -n 1 -o app2_key.hex     # App 2 encryption key  
sseed bip85 password -i master.txt -l 32 -n 0 -o app.pwd     # Application password
```

**[🎯 Complete BIP85 Documentation →](capabilities/bip85-deterministic-entropy.md)**

## 📚 API Documentation

For programmatic integration, SSeed provides a clean Python API:

```python
from sseed import generate_mnemonic, create_shards, restore_mnemonic

# Generate secure mnemonic
mnemonic = generate_mnemonic()

# Create threshold shards
shards = create_shards(mnemonic, groups="3-of-5")

# Restore from shards
restored = restore_mnemonic(shards[:3])
```

**[📖 Full API Documentation →](docs/api.md)**

## 🛠️ Installation Options

### From PyPI (Recommended)
```bash
pip install sseed
```

### From Source
```bash
git clone https://github.com/ethene/sseed.git
cd sseed
pip install .
```

### Development Setup
```bash
# Install in development mode
pip install -e ".[dev]"

# Run comprehensive test suite
pytest  # 290+ tests with 87.8% coverage

# Version management (follows PEP 440)
make bump-patch          # 1.0.1 → 1.0.2
make bump-minor          # 1.0.1 → 1.1.0
make bump-major          # 1.0.1 → 2.0.0
make bump-patch DRY_RUN=1  # Preview changes

# Quality assurance
make test               # Run tests with coverage
make check             # Code quality checks
make ci-test           # Run CI-style tests (lint + mypy + pytest)
make build             # Build distribution packages
```

## 🔧 Command Reference

| Command | Purpose | Example |
|---------|---------|---------|
| `sseed version` | Show version and system info | `sseed version --json` |
| `sseed gen` | Generate BIP-39 mnemonic | `sseed gen -l es -o backup.txt` |
| `sseed seed` | Generate BIP-32 master seed from BIP-39 mnemonic | `sseed seed -i mnemonic.txt --hex` |
| `sseed bip85` | Generate BIP85 deterministic entropy | `sseed bip85 bip39 --words 12 --index 0` |
| `sseed shard` | Split into SLIP-39 shards | `sseed shard -g 3-of-5 -i seed.txt` |
| `sseed restore` | Reconstruct from shards | `sseed restore shard*.txt` |

### Configuration Examples

**Simple Threshold:**
- `3-of-5` - Any 3 of 5 shards required

**Multi-Group Security:**
- `2:(2-of-3,3-of-5)` - Need 2 groups: 2-of-3 AND 3-of-5 shards

**Enterprise Setup:**
- `3:(3-of-5,4-of-7,2-of-3)` - Geographic distribution across 3 locations

## 🔒 Security Features

- ✅ **Cryptographically secure entropy** using `secrets.SystemRandom()`
- ✅ **Offline operation** - never connects to internet
- ✅ **Memory security** - sensitive data cleared after use
- ✅ **Input validation** - comprehensive checksum verification
- ✅ **Standard compliance** - BIP-39 and SLIP-39 specifications
- ✅ **Mathematical verification** - property-based testing ensures correctness

### Standards Compliance

**BIP-39 Implementation:**
- Full BIP-39 specification compliance for mnemonic generation
- 2048-word English wordlist with 11 bits per word
- SHA-256 based checksum validation
- PBKDF2-HMAC-SHA512 for master seed derivation (2048 iterations default)

**SLIP-39 Implementation:**
- **Standard**: SLIP-0039 (SatoshiLabs Improvement Proposal 39)
- **Library**: `shamir-mnemonic` v0.3.0 (Official Trezor reference implementation)
- **Word List**: 1024-word SLIP-39 wordlist (10 bits per word, 4-8 characters each)
- **Algorithm**: Shamir's Secret Sharing in GF(256) finite field
- **Security**: Information-theoretic security with perfect secrecy
- **Maintainers**: Trezor/SatoshiLabs team (matejcik, satoshilabs, stick)
- **Specification**: https://github.com/satoshilabs/slips/blob/master/slip-0039.md

### Cross-Tool Compatibility

SSeed is fully compatible with the official Trezor `shamir` CLI tool from [python-shamir-mnemonic](https://github.com/trezor/python-shamir-mnemonic):

- **Perfect Interoperability**: Both use `shamir-mnemonic==0.3.0`
- **Interchangeable Shards**: SLIP-39 shards work between both tools
- **No Vendor Lock-in**: Migrate freely between implementations

```bash
# Install official Trezor CLI alongside sseed
pip install shamir-mnemonic[cli]

# Full cross-tool compatibility
sseed shard -i mnemonic.txt -g 2-of-3 --separate -o shards
shamir recover  # Works with sseed-generated shards

shamir create 2of3  # Create with official Trezor tool
sseed restore shard1.txt shard2.txt  # Recover with sseed
```

## ⚡ Performance

| Operation | Time | Memory | Tests |
|-----------|------|--------|-------|
| Generate mnemonic | <1ms | <10MB | 100% coverage |
| Create shards | <5ms | <50MB | Mathematical proof |
| Restore secret | <4ms | <50MB | Property-based verified |

**Benchmarks:** Exceeds enterprise requirements by 5-75x

## 🧪 Quality Assurance

- **87.0% test coverage** with 300+ comprehensive tests
- **Property-based testing** using Hypothesis framework
- **9.86/10 code quality** score (Pylint)
- **Zero security vulnerabilities** (Bandit audit)
- **Mathematical verification** of cryptographic properties

## 📋 Requirements

- **Python:** 3.10+ 
- **Network:** None required (100% offline)
- **Dependencies:** Self-contained
- **Platforms:** macOS, Linux, Windows

## 🤝 Contributing

Contributions welcome! Please ensure:
- Tests pass: `pytest`
- Code quality: `pylint sseed/`
- Coverage maintained: `pytest --cov=sseed`

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## ⚠️ Security Notice

**For Educational and Legitimate Use Only**

- Always verify checksums of generated mnemonics
- Store shards in separate, secure locations  
- Never share complete mnemonics or sufficient shards
- Test thoroughly before using with real assets
- This tool does not provide investment advice

---

**Made with ❤️ for the cryptocurrency community**