26 lines
2.2 KiB
Markdown
26 lines
2.2 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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.
|