Handy-Dandy Encrypted Notebook

A terminal-based encrypted notes app written in Python using the Textual TUI framework. Each note in the notebook is an encrpyted text file.

Notes are stored as encrypted files under ~/.notebook/hdnotes/ and can be exported to plaintext if desired.

Developed and used on Unix-like systems. No effort has been made to support Windows.

---

Features

• Seamless first-run setup

  • Auto-generates ~/.notebook/config.json on first run
  • Prompts for a master password
  • Creates/stores note files in ~/.notebook/hdnotes/

• Interactive Textual TUI

  • Directory tree + editor workflow
  • Numbered lines in editor

• Export

  • Export an encrypted note to a plaintext file

• Robust error handling

  • Informative pop-ups on common errors and actions
  • Full tracebacks on unexpected exceptions (useful for debugging)

• Lightweight

  • Single Python script
  • Minimal dependencies (pinned via requirements.txt)

---

Security / Cryptography

This project uses the cryptography library:

• A user-provided passphrase is processed with PBKDF2-HMAC-SHA256 (with a random salt and 100,000 iterations) to derive a key.
• A randomly-generated 256-bit master key is encrypted using AES-256-GCM and stored in ~/.notebook/config.json (base64-encoded fields).
• Each note is encrypted using AES-256-GCM with a fresh random 96-bit (12-byte) nonce per file encryption.
• Note file format is: nonce (12 bytes) || AESGCM(ciphertext+tag).

Important notes:

• Exporting creates plaintext on disk. Treat exported files as sensitive.
• Plaintext export is intentionally convenient; it's a decrypted copy (see above!).
• If you forget the master password, existing notes cannot be decrypted (there is no recovery mechanism).
• Back up ~/.notebook/config.json and ~/.notebook/hdnotes/ together.
• Without the correct master password (and config), notes can’t be decrypted.

---

Requirements

• Python 3.x
• Unix-like OS (e.g., *BSD/Linux/macOS)
• Python packages from requirements.txt (notably: textual, cryptography)

---

Installation

1. Download the current release and unpack the archive
2. Install dependencies:

pip install -r requirements.txt

---

Usage

Run

From the release directory:

chmod 750 hdnotebook.py
./hdnotebook.py

or:

python3 hdnotebook.py

Optional (recommended): copy hdnotebook.py somewhere in your PATH (e.g. ~/.local/bin/, ~/bin/) and make it executable.

Create / Edit Notes

Key bindings:

• Ctrl+N — create a new note
• Ctrl+S — save the current note
• Ctrl+B — toggle the file tree (show/hide)

Workflow:

• Toggle the tree with Ctrl+B, select a note to open/edit it, or
• Create a new note with Ctrl+N, enter a filename, then edit as usual.
• Save changes with Ctrl+S.
• Quit session with Ctrl+Q.

Export Notes

• F2 — export the currently-selected note to plaintext.

Export behavior:

• The plaintext export is written as NOTE_FILENAME.txt in ~/.notebook/hdnotes/.
• The export is UTF-8.
• Export overwrites any existing NOTE_FILENAME.txt in that directory.

---

File Locations

• Config: ~/.notebook/config.json
• Encrypted notes directory: ~/.notebook/hdnotes/

---

Author

J Adams
jfa63[at]duck[dot]com
Dec 2025