2.2 KiB
Repository Guidelines
Project Structure & Module Organization
The repo is intentionally small: salt.py is a reference implementation that demonstrates secure PBKDF2 hashing, while salt2.py wraps the same logic in a CLI with verify mode. Keep new helpers alongside these modules only if they remain single-file utilities; otherwise scaffold a package under salt/ and mirror tests in tests/. Generate derived assets (sample salts, fixtures) in artifacts/ and never commit secrets or real user data.
Build, Test, and Development Commands
Run quick manual checks directly:
python3 salt.py "MySecret" # prints salt + hash
python3 salt2.py verify <pw> <salt> <hash> # exit 0 on success
Add dependencies to requirements.txt if you introduce new libraries. For automated validation add pytest and expose a default target:
python3 -m pytest # runs unit tests
python3 -m pytest -k verify --maxfail=1 -vv
Coding Style & Naming Conventions
Target Python 3.11+, 4-space indentation, and type-annotate public functions. Use descriptive, lowercase_with_underscores names for variables and helper functions; reserve CapWords for classes if you introduce them. Favor stdlib modules (hashlib, secrets, base64) before external choices. Keep scripts executable (#!/usr/bin/env python3) and guard entry points with if __name__ == "__main__":.
Testing Guidelines
Pin tests under tests/test_<feature>.py and mirror module names (e.g., tests/test_hashing.py). Cover both happy paths and failure handling (invalid base64, mismatched hashes). Include property-style assertions such as round-tripping hash_password output into verify_password. When adding algorithms, require regression tests with representative salts and ensure coverage stays above 90% for the hashing utilities.
Commit & Pull Request Guidelines
Use short, imperative subject lines (e.g., feat: add argon2 hashing option) and describe motivation plus key changes in the body. Reference related issues with Fixes #ID when applicable. Open PRs only after tests pass, include reproduction or CLI output for security changes, and add screenshots or logs if the behavior affects tooling UX. Keep PRs focused; split large refactors into reviewable chunks.