hrcx 1.2.2

Split your files into encrypted fragments without needing all fragments for reconstruction!

🔮 Horcrux

Split your files into encrypted fragments using Shamir's Secret Sharing Scheme. No passwords to remember. Just keep your horcruxes safe :)

Horcrux is a file encryption and splitting tool that divides your sensitive files into multiple encrypted fragments (horcruxes). You can configure it so that only a subset of these fragments is needed to reconstruct the original file, providing both security and redundancy.

✨ Features

• 🔐 Secure Encryption: AES-256-GCM encryption for your files
• 🧩 Threshold Scheme: Split into N parts, require only K parts to reconstruct
• 🎯 No Passwords: No need to remember complex passphrases years later
• 📦 Easy Distribution: Spread horcruxes across multiple locations/media
• 🚀 Simple CLI: Intuitive command-line interface
• 🎨 Interactive Mode: Beautiful GUI-like interface for non-technical users
• 🔄 Cross-platform: Works on Windows, macOS, and Linux
• 📊 Metadata Preservation: Maintains original filename and timestamp information

📋 Table of Contents

• Installation
• Quick Start
• Usage
• How It Works
• Use Cases
• API Documentation
• Development
• Contributing
• License
• Acknowledgments

📦 Installation

Via pip (Recommended)

pip install hrcx

Via pipx (Isolated)

pipx install hrcx

From Source

git clone https://github.com/juliuspleunes4/horcrux.git
cd horcrux
pip install -e .

🚀 Quick Start

Split a File

# Split diary.txt into 5 horcruxes (any 3 required to reconstruct)
hrcx split diary.txt -t 5 -k 3

# Output:
# ✓ Created diary_1_of_5.hrcx
# ✓ Created diary_2_of_5.hrcx
# ✓ Created diary_3_of_5.hrcx
# ✓ Created diary_4_of_5.hrcx
# ✓ Created diary_5_of_5.hrcx

Bind Horcruxes Back

# Reconstruct from horcruxes in current directory
hrcx bind

# Or specify a directory
hrcx bind ./horcruxes

# Output:
# ✓ Found 5 horcruxes
# ✓ Threshold met (3 required, 5 available)
# ✓ Successfully reconstructed: diary.txt

📖 Usage

Getting Help

# Show help for main command
hrcx --help

# Show help for split command
hrcx split --help

# Show help for bind command
hrcx bind --help

# Check version
hrcx --version

Split Command

Split a file into multiple encrypted horcruxes:

hrcx split <file> [options]

Options:

• -t, --total <number> - Total number of horcruxes to create (default: prompts user)
• -k, --threshold <number> - Minimum horcruxes needed to reconstruct (default: prompts user)
• -o, --output <directory> - Output directory for horcruxes (default: current directory)

Examples:

# Interactive mode (prompts for total and threshold)
hrcx split secret.pdf

# Split into 7 parts, any 4 can reconstruct
hrcx split secret.pdf -t 7 -k 4

# Specify output directory
hrcx split secret.pdf -t 5 -k 3 -o ./vault

Bind Command

Reconstruct the original file from horcruxes:

hrcx bind [directory] [options]

Options:

• -o, --output <file> - Output file path (default: original filename)
• -f, --force - Overwrite existing file without prompting

Examples:

# Bind horcruxes from current directory
hrcx bind

# Bind from specific directory
hrcx bind ./vault

# Force overwrite existing file
hrcx bind -f

# Specify output location
hrcx bind -o ./recovered/secret.pdf

Interactive Mode

For non-technical users, Horcrux offers a beautiful interactive mode with a guided wizard:

hrcx interactive

Features:

• 🎨 Beautiful ocean-blue ASCII art header
• 🎯 Step-by-step guided workflows
• 🌈 Color-coded prompts (green for success, red for errors, yellow for warnings)
• ✅ Automatic validation of all inputs
• 📁 Smart file discovery and defaults
• 🔄 Perform multiple operations in one session

Windows Users: Simply double-click the horcrux.bat file to launch interactive mode without opening a terminal!

Interactive mode walkthrough:

1. Choose between Split or Bind operations
2. Follow the color-coded prompts:
   • Split: Select file → Set total horcruxes → Set threshold → Choose output directory
   • Bind: Select horcrux directory → Confirm reconstruction → Choose output location
3. Review the summary and confirm
4. Watch as your operation completes with visual feedback

Perfect for users who prefer a GUI-like experience or are new to command-line tools!

🔬 How It Works

Horcrux uses a combination of Shamir's Secret Sharing Scheme and AES-256-GCM encryption:

1. Key Generation: A random 256-bit encryption key is generated using a cryptographically secure random number generator

2. File Encryption: The original file is encrypted using AES-256 in GCM (Galois/Counter Mode) for authenticated encryption

3. Secret Sharing: The encryption key is split into N fragments using Shamir's Secret Sharing algorithm, configured so that any K fragments can reconstruct the key

4. Horcrux Creation: Each fragment is embedded in a horcrux file along with:

   • Encrypted file data (distributed across all horcruxes)
   • Metadata (original filename, timestamp, index, threshold)
   • Key fragment for reconstruction

5. Reconstruction: When binding:

   • Collect K or more horcruxes
   • Reconstruct the encryption key using Shamir's algorithm
   • Decrypt and reassemble the original file

Shamir's Secret Sharing

This cryptographic algorithm allows a secret (the encryption key) to be divided into N shares, where any K shares can reconstruct the secret, but K-1 shares reveal nothing about it. This is accomplished using polynomial interpolation over a finite field.

Mathematical Foundation:

• Generate a random polynomial of degree K-1 with the secret as the constant term
• Evaluate the polynomial at N different points to create N shares
• Any K shares can reconstruct the polynomial (and thus the secret) using Lagrange interpolation

💡 Use Cases

Personal Use

• Sensitive Documents: Split personal records, tax documents, or legal papers
• Cryptocurrency Wallets: Distribute wallet backups across multiple secure locations
• Password Manager Databases: Add an extra layer of security to password vaults
• Photo Albums: Protect private photos from single-point compromise

Professional Use

• Distributed Backups: Store critical business data across multiple geographic locations
• Multi-party Access: Require collaboration from multiple parties to access sensitive information
• Secure Transmission: Send file fragments through different communication channels to prevent interception
• Disaster Recovery: Ensure data can be recovered even if some backup locations are compromised

Who This Is For

• People who need to encrypt sensitive files without remembering passwords years later
• Organizations requiring multi-party authorization for sensitive data access
• Users who want to distribute backups across multiple physical locations
• Anyone named Tom Riddle 🐍

📚 API Documentation

Horcrux can also be used as a library in your Python projects:

Installation

pip install hrcx

Usage

from hrcx import split, bind

# Split a file
split(
    file_path='./secret.txt',
    total=5,
    threshold=3,
    output_dir='./horcruxes'
)

# Bind horcruxes
bind(
    horcrux_paths=['./horcruxes/secret_1_of_5.hrcx', './horcruxes/secret_2_of_5.hrcx', './horcruxes/secret_3_of_5.hrcx'],
    output_path='./recovered.txt'
)

API Reference

split(file_path: str, total: int, threshold: int, output_dir: Optional[str] = None) -> None

Splits a file into encrypted horcruxes.

Parameters:

• file_path (str): Path to the file to split
• total (int): Total number of horcruxes to create (must be >= threshold)
• threshold (int): Minimum number of horcruxes needed to reconstruct (must be >= 2)
• output_dir (Optional[str]): Output directory for horcruxes (default: same directory as input file)

Raises:

• FileNotFoundError: If the input file doesn't exist
• ValueError: If total < threshold or threshold < 2
• PermissionError: If unable to write to output directory

Example:

from hrcx import split

split('secret.pdf', total=7, threshold=4, output_dir='./vault')

bind(horcrux_paths: Optional[List[str]] = None, output_path: Optional[str] = None, overwrite: bool = False) -> None

Reconstructs the original file from horcruxes.

Parameters:

• horcrux_paths (Optional[List[str]]): List of paths to horcrux files. If None, auto-discovers horcruxes in current directory
• output_path (Optional[str]): Output file path (default: original filename from horcrux metadata)
• overwrite (bool): Whether to overwrite existing file without prompting (default: False)

Raises:

• FileNotFoundError: If no horcrux files found
• ValueError: If insufficient horcruxes or incompatible horcruxes provided
• RuntimeError: If decryption fails or file integrity check fails

Example:

from hrcx import bind

# Auto-discover horcruxes in current directory
bind()

# Specify horcruxes explicitly
bind(
    horcrux_paths=['./vault/secret_1_of_7.hrcx', './vault/secret_4_of_7.hrcx', './vault/secret_6_of_7.hrcx', './vault/secret_7_of_7.hrcx'],
    output_path='./recovered.pdf',
    overwrite=True
)

🛠 Development

Prerequisites

• Python >= 3.8
• pip >= 21.0

Setup

# Clone the repository
git clone https://github.com/juliuspleunes4/horcrux.git
cd horcrux

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/

# Format code
black src/ tests/

# Type checking
mypy src/

Project Structure

horcrux/
├── src/hrcx/
│   ├── cli.py         # Command-line interface
│   ├── crypto/        # Encryption and key management
│   ├── shamir/        # Shamir's Secret Sharing implementation
│   ├── horcrux/       # Horcrux file handling
│   └── utils/         # Utility functions
├── tests/             # Test files
├── docs/              # Documentation
└── pyproject.toml     # Package configuration

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=hrcx --cov-report=html

# Run specific test file
pytest tests/test_api.py

# Run with verbose output
pytest -v

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to:

• Update tests as appropriate
• Follow the existing code style
• Update documentation for API changes
• Add entries to CHANGELOG.md

🔒 Security

Reporting Vulnerabilities

If you discover a security vulnerability, please email [e-mail] instead of using the issue tracker.

Security Considerations

• Horcruxes are encrypted with AES-256-GCM, providing strong confidentiality and authenticity
• The encryption key is generated using crypto.randomBytes() for cryptographic security
• Shamir's Secret Sharing is implemented over GF(256) using standard polynomial interpolation
• Each horcrux contains metadata in plaintext (filename, timestamp, indices) for convenience
• The threshold scheme ensures that K-1 horcruxes reveal no information about the original file

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project was inspired by and adapted from the excellent horcrux project by Jesse Duffield, originally written in Go. The core concepts, including the use of Shamir's Secret Sharing Scheme and the creative Harry Potter theming, are credited to the original project.

Original Project:

• Repository: jesseduffield/horcrux
• Author: Jesse Duffield
• License: MIT

Additional Credits:

• Shamir's Secret Sharing implementation adapted from Hashicorp Vault
• Inspired by the Harry Potter universe created by J.K. Rowling

Other Projects by Jesse Duffield

Check out Jesse's other amazing projects:

• Lazygit - Simple terminal UI for git commands
• Lazydocker - Terminal UI for Docker and docker-compose
• OK? Programming Language - An experimental programming language

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki

🗺 Roadmap

• GUI application for non-technical users
• Support for streaming large files
• Cloud storage integration (AWS S3, Google Drive, etc.)
• Mobile app (iOS/Android)
• Verification mode to check horcrux integrity
• Compression before encryption
• Custom encryption algorithms support

⚠️ Disclaimer

This software is provided "as is" without warranty of any kind. While Horcrux uses industry-standard encryption and secret sharing algorithms, the security of your data ultimately depends on how you store and protect your horcruxes. Always keep backups of important data.

---

Made with ❤️

If you find this project useful, please consider giving it a ⭐️ on GitHub!