:cover: https://github.com/HaoZeke/nimvault/blob/main/branding/logo/nimvault.svg

============
``nimvault``
============

:Author: `Rohit Goswami <https://rgoswami.me>`_

.. image:: ../../branding/logo/nimvault.svg

Architecture
------------

``nimvault`` is a single static binary that encrypts files into opaque GPG blobs
with randomized filenames. Only the encrypted blobs and an encrypted manifest
are committed to git; the original filenames and contents never appear in
version history.

.. image:: architecture.svg

Overview
--------

``nimvault`` stores sensitive files with opaque filenames and encrypted contents
using GPG. Both the original filenames and file contents are hidden from git
history: only random hex blob names and a GPG-encrypted manifest are committed.

The tool is designed for dotfile managers like `chezmoi <https://www.chezmoi.io/>`_ where secrets need to
travel across machines via git without exposing their contents or even their
names.

Key properties
~~~~~~~~~~~~~~

Opaque filenames
    Each file is assigned a 16-character random hex ID
    generated from 8 bytes of cryptographic randomness (``std/sysrand``).

Signed and verified
    The manifest is signed (GPG in-band, or a detached
    SSH signature for age). v6 payloads have no in-band signature; authenticity
    is the signed manifest plus each blob digest. ``unseal`` checks those before
    writing any plaintext (atomic, fail-closed).

Parallel GPG
    Encryption and decryption spawn GPG processes in parallel via
    ``startProcess`` for fast batch operations.

Portable paths
    Paths under ``$HOME`` are stored with ``~/`` prefix so the
    manifest works across machines.

3-tier recipient resolution
    The GPG recipient is resolved from (1) CLI
    ``--recipient`` flag, (2) ``NIMVAULT_GPG_RECIPIENT`` environment variable, or (3)
    ``.vault/config`` file. First non-empty value wins.

Backends
    GPG backend needs ``gpg`` on PATH. Age backend needs ``age`` (or
    ``rage``) and ``ssh-keygen`` for the detached manifest signature.

Module structure
----------------

The library is split into four focused modules, each with a single
responsibility.

.. image:: modules.svg

Quick checklist
---------------

1. Install Nim >= 2.0 and GPG

2. ``nimble install nimvault``

3. ``cd`` into a git repo

4. Create ``.vault/config`` with ``recipient = YOUR_KEY_ID``

5. ``nimvault add ~/.secret/file.txt``

6. ``nimvault seal``

7. ``git add .vault/ && git commit``

8. On another machine: ``git pull && nimvault unseal``

9. ``nimvault status`` to verify sync state

Getting Started
---------------

  .. toctree::
     :maxdepth: 1
     :caption: Getting Started

     quickstart
     tutorials/directory-support

Guides
------

  .. toctree::
     :maxdepth: 1
     :caption: How-To Guides

     howto/keybase
     howto/chezmoi
     howto/private-vault-repo
     howto/service-vault
     howto/headless-gpg

Reference
---------

  .. toctree::
     :maxdepth: 2
     :caption: Reference

     reference/cli
     reference/config
     reference/manifest
     explanation/threat-model

Development
-----------

  .. toctree::
     :maxdepth: 2
     :caption: Development

     contributing/index
     changelog