Metadata-Version: 2.4
Name: sseed
Version: 1.0.1
Summary: Offline BIP39/SLIP39 CLI Tool for secure cryptocurrency seed management
Author-email: sseed <shroomshroom@gmail.com>
License-Expression: MIT
Keywords: bip39,slip39,cryptocurrency,mnemonic,seed,cli,offline
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bip-utils>=2.9.3
Requires-Dist: slip39>=13.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.5; extra == "dev"
Requires-Dist: mypy>=1.16.1; extra == "dev"
Requires-Dist: ruff>=0.12.0; extra == "dev"
Requires-Dist: bandit>=1.8.5; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Dynamic: license-file

# SSeed - Offline BIP39/SLIP39 CLI Tool

A minimalistic Python command-line tool for secure cryptocurrency seed management that works completely offline.

## Features

- 🔐 **Generate secure 24-word BIP-39 mnemonics** using cryptographically secure entropy
- 🔄 **Split mnemonics into SLIP-39 shards** with customizable group/threshold configurations  
- 🔧 **Reconstruct mnemonics from shards** with integrity validation
- 🚫 **100% offline operation** - no internet calls ever made
- ⚡ **High performance** - operations complete in milliseconds
- 🛡️ **Secure memory handling** - sensitive data is properly cleared
- 🎯 **Simple CLI interface** - easy to use and integrate

## Installation

Install sseed from PyPI:

```bash
pip install sseed
```

Or install from source:

```bash
git clone <repository-url>
cd sseed
pip install .
```

For development:

```bash
pip install -e ".[dev]"
```

## Quick Start

### Generate a BIP-39 Mnemonic

```bash
# Generate to stdout
sseed gen

# Generate to file
sseed gen -o my_seed.txt
```

### Create SLIP-39 Shards

```bash
# Create 3-of-5 shards from a mnemonic
sseed shard -i my_seed.txt -g 3-of-5 -o shards.txt

# Create separate files for each shard
sseed shard -i my_seed.txt -g 3-of-5 --separate -o shards
```

### Restore from Shards

```bash
# Restore from shard files
sseed restore shard1.txt shard2.txt shard3.txt

# Restore from stdin
cat shards.txt | sseed restore
```

## Command Reference

### `sseed gen`
Generate a 24-word BIP-39 mnemonic using secure entropy.

**Options:**
- `-o, --output FILE` - Output file (default: stdout)

### `sseed shard`
Split a BIP-39 mnemonic into SLIP-39 shards.

**Options:**
- `-i, --input FILE` - Input mnemonic file (default: stdin)
- `-g, --groups CONFIG` - Group configuration (e.g., "3-of-5", "2:(2-of-3,3-of-5)")
- `-o, --output FILE` - Output file (default: stdout)
- `--separate` - Write shards to separate files
- `-p, --passphrase TEXT` - Optional passphrase for additional security

### `sseed restore`
Reconstruct a mnemonic from SLIP-39 shards.

**Arguments:**
- `SHARD_FILES...` - Shard files to restore from (or use stdin if none provided)

**Options:**
- `-p, --passphrase TEXT` - Passphrase if one was used during sharding

## Security Features

- **Cryptographically secure entropy** using `secrets.SystemRandom()`
- **No network calls** - operates completely offline
- **Secure memory handling** - sensitive data is cleared after use
- **Input validation** - comprehensive checksum and format validation
- **BIP-39 compliance** - full BIP-39 standard compliance
- **SLIP-39 standard** - implements SLIP-39 specification

## File Formats

All files use plain text UTF-8 encoding with optional comments:

```
# BIP-39 Mnemonic File
# Generated by sseed on 2024-06-19 13:50:27
#
abandon ability able about above absent absorb abstract absurd abuse access accident
```

Comments (lines starting with `#`) are ignored during processing.

## Group Configurations

SLIP-39 supports flexible threshold schemes:

- **Simple**: `"3-of-5"` - requires 3 out of 5 shards
- **Multi-group**: `"2:(2-of-3,3-of-5)"` - requires 2 groups, with 2-of-3 shards from first group and 3-of-5 from second

## Performance

SSeed is optimized for performance:

- **Mnemonic generation**: < 1ms average
- **SLIP-39 sharding**: < 5ms average  
- **Shard reconstruction**: < 4ms average
- **Memory usage**: < 2MB additional memory

## Requirements

- Python 3.10 or higher
- No external network access required
- Cross-platform: macOS, Linux, Windows

## Development

### Running Tests

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run specific test categories
pytest tests/test_bip39.py
pytest tests/test_slip39.py
pytest tests/test_performance_security.py
```

### Code Quality

```bash
# Type checking
mypy sseed/

# Linting and formatting
ruff check sseed/
ruff format sseed/

# Security audit
bandit -r sseed/
```

## License

MIT License. See LICENSE file for details.

## Security Notice

⚠️ **Important Security Considerations:**

- Always verify checksums of generated mnemonics
- Store shards in separate, secure locations
- Never share your complete mnemonic or sufficient shards publicly
- This tool is for educational and legitimate use only
- Test thoroughly before using with real cryptocurrency assets

## Contributing

Contributions are welcome! Please ensure all tests pass and follow the existing code style.

## Changelog

### v0.1.0
- Initial release
- BIP-39 mnemonic generation
- SLIP-39 sharding and reconstruction
- Complete offline operation
- Comprehensive test suite
- Security audit passed 
