vaultlog

Python 3.11+ AES-256-GCM PBKDF2-HMAC-SHA256 Textual TUI cryptography Security MIT

GitHub: stevenvo780/vaultlog

---

What it is

vaultlog is a CLI + TUI journal where every entry lives as ciphertext on disk, unlocked with a single master password and optionally backed up to a private Git repository — without ever committing plaintext.

The master password is never stored. It is used exclusively to derive a 32-byte key in memory; the derived key and the password are discarded as soon as the vault is locked. If the password is lost, the encrypted content cannot be recovered.

Component	Role
vaultlog/crypto.py	PBKDF2-HMAC-SHA256 key derivation + AES-256-GCM encrypt/decrypt
vaultlog/store.py	Vault CRUD — atomic writes, manifest, password rotation with staged re-encryption
vaultlog/tui.py	Textual TUI — sidebar, markdown editor, panic mode (F8), idle auto-lock
vaultlog/cli.py	argparse CLI — init, open, new, backup, verify, doctor, and more
vaultlog/gitops.py	Git backup engine + embedded pre-commit hook script
scripts/build_deb.sh	Reproducible .deb packaging with bundled venv under /opt/vaultlog/

---

Encryption architecture

1. Key derivation. On init, a random 16-byte salt is generated. The master password and salt are run through PBKDF2-HMAC-SHA256 (390 000 iterations) to produce a 32-byte key. Salt and iteration count go into config.json; the password and derived key do not.
2. Verifier. A small known payload is encrypted with the derived key and stored in the config. On unlock, vaultlog re-derives the key and decrypts the verifier to confirm the password.
3. Per-record encryption. Each entry and the manifest are serialized to JSON and sealed with AES-256-GCM. A fresh random 12-byte nonce is generated per encryption call; GCM provides both confidentiality and tamper detection.
4. On-disk layout (default ./.vaultlog/):
   • config.json — version, salt, KDF iterations, encrypted verifier, settings. No plaintext content.
   • manifest.enc — encrypted index of entry metadata.
   • entries/<id>.enc — one encrypted file per entry.
5. Password rotation re-encrypts the entire vault into a staging directory, verifies it decrypts cleanly, then atomically swaps it in and timestamps the previous state.

---

Installation

From source (development)

git clone https://github.com/stevenvo780/vaultlog.git
cd vaultlog
python3 -m venv .venv
.venv/bin/pip install -e .
# The `vaultlog` command is now available inside the venv

Debian package (.deb)

git clone https://github.com/stevenvo780/vaultlog.git
cd vaultlog
python3 -m venv .venv && .venv/bin/pip install -e .
scripts/build_deb.sh
# Output: dist/vaultlog_<version>_<arch>.deb
sudo dpkg -i dist/vaultlog_*.deb
# Installs self-contained under /opt/vaultlog/; adds /usr/bin/vaultlog shim

Run the tests

python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests
# Covers: crypto roundtrip, store CRUD + password rotation,
#         git backup isolation, pre-commit hook enforcement, TUI autosave

Python 3.11+ required

vaultlog uses tomllib (stdlib since 3.11) for the .deb build script and relies on cryptography>=48 for AESGCM and PBKDF2HMAC. The .deb bundle ships its own venv so the installed command does not require the checkout.

---

Usage

Initialize a new vault (prompts for master password):

vaultlog init

Open the TUI editor:

vaultlog open

Common CLI commands:

# List all entries (metadata only)
vaultlog list

# Create an entry — prefer --body-stdin to avoid shell history leaks
echo "my private note" | vaultlog new --title "daily log" --body-stdin

# Show a decrypted entry; use --metadata-only to avoid scrollback exposure
vaultlog show daily-log --metadata-only

# Verify all entries decrypt correctly
vaultlog verify

# Encrypted Git backup (init repo inside vault, push to private remote)
vaultlog backup --init-git --remote git@github.com:YOU/PRIVATE_VAULT.git --push

# Rotate master password (staged re-encryption, atomic swap)
vaultlog change-password

# Quick health check
vaultlog doctor --verify

# Install the pre-commit hook in the project repo
vaultlog install-git-hook

---

TUI shortcuts

Key	Action
Ctrl+N	New entry
Ctrl+R	Rename entry
Ctrl+S	Save
Ctrl+B	Verify, commit, and push the encrypted vault
Ctrl+L	Lock the session
F8	Panic mode — camouflage the screen as ordinary source code
Ctrl+G	Focus the entry list
Ctrl+E	Focus the editor
Ctrl+Q	Quit

Pre-commit hook required for Git backup

Keep vault data in its own private Git repo, never in the project repo. Run vaultlog install-git-hook to block recovery notes, plaintext files, private keys (PEM headers), and sensitive filenames from being committed. The hook is enforced in both the project repo and the dedicated vault repo.

---

Stack

Layer	Technology
Authenticated encryption	AES-256-GCM (cryptography.hazmat.primitives.ciphers.aead.AESGCM)
Key derivation	PBKDF2-HMAC-SHA256, 390 000 iterations (cryptography.hazmat.primitives.kdf.pbkdf2)
TUI framework	Textual >=8.2
CLI	argparse (stdlib)
Atomic writes	os.replace + fsync (stdlib)
Git backup	subprocess calling git (no extra dep)
Packaging	setuptools + scripts/build_deb.sh → .deb with bundled venv
Runtime	Python 3.11+
License	MIT