Skip to content

README.md

Latest commit

 

History

History
169 lines (148 loc) · 6.32 KB

README.md

File metadata and controls

169 lines (148 loc) · 6.32 KB

VaultGuard

Secure Wallet Storage and Recovery Tool

C++23 CMake License: MIT PRs Welcome

Overview

VaultGuard is a C++26 application for securely storing and recovering cryptocurrency wallets (private keys and seed phrases) on an encrypted USB drive. It leverages libsodium for strong cryptography, simulates a blockchain-like structure for redundancy, and supports cross-platform USB management.

graph TD
    A[Start VaultGuard] --> B[Show Welcome Screen]
    B --> C{Is USB with VaultGuard Data Detected?}
    C -->|Yes| D[Enter Password]
    C -->|No| E[Prepare USB Menu]
    D --> F{Password Correct?}
    F -->|Yes| G[Main Menu]
    F -->|No| H[Password Incorrect, Try Again]
    H --> D
    G --> I{User Choice}
    I -->|1: Store Wallet| J[Enter Wallet Details: ID, Name, Currency, Key, Seed<br>Or read from file]
    J --> K[Encrypt Data with Password<br>Argon2 derives key, XChaCha20-Poly1305 encrypts]
    K --> L[Store in 3 Sectors: vault_sectors.dat<br>Sectors 1000, 1100, 1200; includes salt, nonce, ciphertext]
    L --> M[Save Backup: vault_key.dat]
    M --> N[Save Wallet Info: vault_index.dat]
    N --> O[Save Wallet: wallet_<ID>.dat]
    O --> G
    I -->|2: Recover Wallet| P[Show Wallets from vault_index.dat]
    P --> Q[Select Wallet]
    Q --> R[Decrypt from vault_sectors.dat or vault_key.dat<br>Password recreates key, decrypts data]
    R --> S[Display once in terminal<br>or export decrypted_wallet_<ID>.txt]
    S --> G
    I -->|3: Change USB| T[Reset USB Config]
    T --> E
    I -->|4: Exit| U[End]
    E --> V{Choose Option}
    V -->|1: Format USB| W[Enter USB Name & Confirm Format]
    W --> X[Generate or Enter Password]
    X --> Y[Format USB to APFS & Store Key<br>Saves to vault_sectors.dat, vault_key.dat]
    Y --> G
    V -->|2: Use Existing USB| Z[Enter Mount Path & Password]
    Z --> AA{Password Correct?}
    AA -->|Yes| G
    AA -->|No| AB[Try Again]
    AB --> Z
    V -->|3: Cancel| U
Loading

Key Features

  • Strong Encryption: Uses Argon2 for key derivation and XChaCha20-Poly1305 for encryption.
  • Redundant Storage: Stores keys in multiple sectors with a blockchain-like approach.
  • Filesystem Fallback: Saves keys to a file if sector storage fails.
  • Cross-Platform: Supports macOS, Linux, and Windows with USB detection and formatting.
  • Secure Input: Validates user inputs and provides secure password generation.
  • Safer Recovery Output: Defaults to one-time terminal display and requires explicit choice for plaintext export files.
  • Automated Verification: Includes CI, unit tests, and integration tests (ctest) for release gating.

Dependencies

  • C++26 Compiler: Clang, GCC, or MSVC with module support.
  • libsodium: Automatically downloaded if not installed (or install manually).
  • CMake: Version 3.26 or higher.

Installing Dependencies

  • macOS (Homebrew): 
    brew install libsodium ninja
  • Linux (Ubuntu): 
    sudo apt-get install libsodium-dev ninja-build
  • Windows (vcpkg): 
    vcpkg install libsodium

Build Instructions

  1. Clone the repository: 
    git clone https://github.com/thecompez/vaultguard.git
cd vaultguard
  2. Create and navigate to build directory: 
    mkdir build
cd build
  3. Configure with CMake: 
    cmake -G Ninja -DBUILD_TESTING=ON ..
    For Windows with vcpkg: 
    cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..
  4. Build: 
    ninja
  5. Run tests: 
    ctest --output-on-failure
  6. Install (optional): 
    cmake --install .

This produces two executables: vaultguard (main app) and recover_key (recovery tool).

Usage

  • Main App: 
    ./vaultguard
    Follow the menu to prepare a USB drive, store, or recover wallets. Wallet IDs must use only letters, numbers, _ or - (max 64 chars).
  • Recovery Tool: 
    ./recover_key <mount_path>
    The tool prompts for the password securely (hidden input).
    Use --show-key only when you explicitly need plaintext output: 
    ./recover_key <mount_path> --show-key
    Example: 
    ./recover_key /Volumes/VAULT

Warning: Run VaultGuard offline on a trusted system (e.g., Tails OS) with a connected USB drive to ensure security.

Project Structure

  • src/: Source files (main.cpp, recover_key.cpp).
  • include/: C++ modules (block.cppm, crypto.cppm, file.cppm, utils.cppm, wallet.cppm).
  • CMakeLists.txt: Build configuration.

Contributing

  1. Fork the repository.
  2. Create a feature branch: git checkout -b my-feature.
  3. Commit changes: git commit -m "Add my feature".
  4. Push to the branch: git push origin my-feature.
  5. Open a pull request.

Follow C++ best practices and include tests where possible.

License

MIT License. See LICENSE for details.

⚠️ Security Notice

VaultGuard is now a production-candidate build with hardened input validation, safer recovery defaults, and automated test/CI gates. External security review is still recommended before high-value deployments. Potential operational risks include:

  • Data Loss: Forgetting the password will render stored data unrecoverable, as no backdoor or recovery mechanism exists.
  • Hardware Failure: If the USB drive fails and no backups are made, data may be lost despite redundancy features.
  • Operational Misuse: Exporting plaintext recovered keys or running on an untrusted/online host can leak secrets.

Use VaultGuard on a secure, offline environment (e.g., Tails OS) and always maintain secure backups of passwords and key material.

Notes

  • Ensure libsodium is installed or let CMake download it automatically.
  • For Windows, set CMAKE_TOOLCHAIN_FILE if using vcpkg.
  • Test thoroughly on a secure, offline system before storing sensitive data.
  • Use the release gate checklist in RELEASE_CHECKLIST.md before promoting a build.