Horcrux — Distributed Threshold Secret Vault

Horcrux is a distributed threshold secret vault built using Shamir’s Secret Sharing. It splits a secret into multiple shares and distributes them across independent nodes (holders), such that only a threshold number (k) of shares can reconstruct the secret.

This ensures:

• No single node can access the secret
• Fault tolerance against node failures
• Strong cryptographic guarantees

---

🚀 Features

• Threshold secret sharing (k, n)
• Distributed holder nodes (independent processes)
• Vault for orchestration and reconstruction
• CLI for end-to-end interaction
• Failure-tolerant unlock flow
• Hash-based secret verification (no secret leakage)

---

🧠 How It Works

1. A secret is split into n shares using Shamir’s Secret Sharing
2. Each share is stored in a separate Holder node
3. The Vault requests shares from holders
4. If ≥ k shares are collected:
   • Secret is reconstructed
   • Hash is returned as proof

---

🏗️ Architecture

flowchart LR
    CLI[CLI] -->|unlock request| Vault

    Vault -->|GET /share| H1[Holder 1]
    Vault -->|GET /share| H2[Holder 2]
    Vault -->|GET /share| H3[Holder 3]
    Vault -->|GET /share| HN[Holder N]

    H1 -->|share| Vault
    H2 -->|share| Vault
    H3 -->|share| Vault
    HN -->|share| Vault

    Vault -->|reconstruct (k shares)| Core[Shamir Core]
    Core --> Vault

    Vault -->|hash output| CLI

Loading

---

📦 Project Structure

crates/
├── horcrux-core     # Cryptographic core (Shamir, field math)
├── horcrux-holder   # Distributed share holders (HTTP nodes)
├── horcrux-vault    # Orchestrator (collect + reconstruct)
└── horcrux-cli      # User interface (entry point)

---

⚙️ Requirements

• Rust (latest stable)
• Cargo
• (Optional) Docker

---

🔧 Setup & Run (Local)

1. Clone the repository

git clone https://github.com/AkZcH/horcrux.git
cd horcrux

---

2. Build everything

cargo build --workspace

---

3. Generate shares (temporary step)

Use your core logic to generate (k, n) shares.

Example:

secret = 123
k = 3
n = 5

Store resulting (x, y) values.

---

4. Start Holder Nodes

Run each holder in a separate terminal:

cargo run -p horcrux-holder -- <x> <y> <port>

Example:

cargo run -p horcrux-holder -- 1 141 3001
cargo run -p horcrux-holder -- 2 500 3002
cargo run -p horcrux-holder -- 3 900 3003

---

5. Run CLI (Unlock)

cargo run -p horcrux-cli -- \
  --k 3 \
  --epoch 0 \
  --holders http://127.0.0.1:3001,http://127.0.0.1:3002,http://127.0.0.1:3003

---

✅ Expected Output

UNLOCK SUCCESS
hash: <hex-value>
shares_used: 3

---

❌ Failure Case Example

If fewer than k nodes respond:

UNLOCK FAILED
reason: INSUFFICIENT_SHARES

---

🐳 Docker (Optional)

docker-compose up --build

This spins up:

• Multiple holders
• Vault service

---

🔒 Security Notes

• Secret is never printed, only hashed
• Holders are isolated and unaware of each other
• Reconstruction is transient (memory-only)

---

⚠️ Limitations (v0)

• No authentication
• No TLS (plaintext HTTP)
• No malicious node protection
• No persistent storage
• Naive share selection (first-k)

---

🧪 Testing

Run all tests:

cargo test --workspace

Includes:

• Unit tests
• Property-based tests
• Integration tests

---

📜 License

MIT License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy...

---

💡 Future Improvements

• Secure share refresh protocol
• Parallel request strategy in vault
• Authentication & TLS
• Persistent holder storage
• Kubernetes deployment

---

👤 Author

Akshat Chauhan

---

⭐ If You Like This Project

Star the repo. Fork it. Break it. Improve it.