🚀 Key Features

• Modular Architecture: Full separation between the cryptographic logic (core) and the CLI/storage interface.
• Interactive Menu (TUI): Running passmgr with no arguments opens an arrow-key navigation menu built with questionary and rich, offering List / Get / Add / Delete / Generate options directly from the menu.
• Strong Security: Key derivation via PBKDF2-HMAC-SHA256 (600,000 iterations by default, following OWASP guidance) and Fernet authenticated encryption (AES-128-CBC + HMAC-SHA256).
• Safe Storage: Atomic vault writes (temporary file, fsync, then replace), so an interrupted save never corrupts the vault; owner-only file permissions (0600 on Linux/macOS).
• Local Encrypted Storage: The vault is stored in a single encrypted file (vault.json).
• Dedicated CLI Shortcut: Run the passmgr command directly from the terminal, with or without subcommands.
• Clipboard Integration: Quick password copying with a single keypress or a CLI flag (using pyperclip). The clipboard is cleared after 30 seconds, and only if it still holds the copied password.
• Testing & CI/CD: pytest suite with coverage reporting on Python 3.10–3.13, and automated PyPI deployment on tagged releases via GitHub Actions.

Project Structure 📂

PASSWORD_MANAGER/
├── .github/
│   └── workflows/
│       ├── publish.yml
│       └── test.yml
├── src/
│   └── password_manager/
│       ├── cli/
│       │   ├── __init__.py
│       │   └── main.py
│       ├── core/
│       │   ├── __init__.py
│       │   ├── crypto.py
│       │   └── vault.py
│       ├── __init__.py
│       └── clipboard.py
├── tests/
│   ├── test_cli.py
│   ├── test_clipboard.py
│   ├── test_crypto.py
│   └── test_vault.py
├── .gitignore
├── LICENSE
├── pyproject.toml
├── README.md
└── requirements.txt

📦 Installation & Running

Option 1: Install from PyPI (Recommended)

pip install razeini-password-manager

Option 2: Install for Development

1. Clone the repository:

git clone https://github.com/RazEini/Password_Manager.git
cd Password_Manager

2. Install the package in editable mode:

pip install -e .

3. Run unit tests:

pip install -r requirements.txt
pytest --cov=src --cov-report=term-missing

🖥️ Interactive Mode (TUI)

passmgr
# or with a specific vault file:
passmgr --vault myvault.json

The menu automatically detects whether the vault exists:

• If it doesn't exist — it will offer to create a new vault with a master password.
• If it exists — it will prompt for the master password to unlock it.

Once unlocked, an arrow-key navigation menu is displayed with the following options:

💻 CLI – Main Commands (`passmgr`)

💡 Note on Custom Vault Names:
By default, passmgr uses vault.json in the current working directory. If you want to use a custom file name (e.g., myvault.json), append --vault <filename> to any command:

passmgr --vault myvault.json init
passmgr --vault myvault.json add --service github --user myusername

🛡️ Security & Key Derivation

The application never stores the master password on disk. The key is derived in real time from the master password and the per-vault random salt stored in the vault file, and the vault file holds only the KDF parameters and the Fernet ciphertext (service names, usernames and notes are encrypted too). Password entry uses getpass in CLI mode and questionary.password in the TUI, so characters are never echoed.

What is in place

• Key derivation: PBKDF2-HMAC-SHA256, 600,000 iterations by default, with a fresh 16-byte salt per vault and on every master-password change.
• Authenticated encryption: Fernet (AES-128-CBC + HMAC-SHA256). A wrong password or a tampered file fails authentication and never yields partial data.
• Durable writes: the vault is written to a temporary file in the same directory, flushed and fsynced, then atomically swapped in with os.replace(). A crash or full disk leaves the previous vault intact.
• File permissions: the vault (and CSV exports) are created owner-only (0600) on Linux and macOS.
• Clipboard hygiene: copied passwords are cleared after 30 seconds, unless you copied something else in the meantime.

Upgrading an older vault. Each vault stores its own iteration count, so vaults created with the previous default (390,000) keep working. passmgr prints a hint when it opens one, and passmgr change-master re-encrypts it at the current default. Passing a lower value with --iterations prints a warning.

Scope and limits

• export-csv writes your passwords in plaintext by design. Delete the file when you are done.
• While the program is running, the master password and decrypted entries exist in process memory; there is no memory locking or secure wipe (a Python limitation).
• On Windows, 0600 maps only to the read-only bit, so rely on the user profile's NTFS permissions.
• Clipboard managers or other programs may read the clipboard before it is cleared.

📄 License

This project is distributed under the MIT license – free to use, modify, and distribute. For more information, see the LICENSE file.

👨‍💻 Raz Eini (2026)