105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a Python PBKDF2 password hashing utility with two implementations:
|
|
- `salt.py`: Reference implementation with CLI that supports both `hash` and `verify` subcommands, plus a shortcut where running `python3 salt.py <password>` automatically invokes the hash command
|
|
- `salt2.py`: Alternative CLI that imports from `salt.py` and requires explicit subcommands (`generate` and `verify`)
|
|
|
|
Both implementations use PBKDF2-HMAC-SHA256 with configurable iteration counts (default: 200,000, overridable via `PBKDF2_ITERATIONS` env var).
|
|
|
|
## Common Commands
|
|
|
|
### Running the CLI
|
|
```bash
|
|
# Hash a password (salt.py supports shortcut syntax)
|
|
python3 salt.py "MyPassword"
|
|
python3 salt.py hash "MyPassword"
|
|
|
|
# Verify a password
|
|
python3 salt.py verify <password> <salt_b64> <hash_b64>
|
|
|
|
# Alternative CLI (requires explicit subcommands)
|
|
python3 salt2.py generate "MyPassword"
|
|
python3 salt2.py verify <password> <salt_b64> <hash_b64>
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all tests
|
|
python3 -m pytest
|
|
|
|
# Run specific tests with verbose output
|
|
python3 -m pytest -k verify --maxfail=1 -vv
|
|
|
|
# Run tests for a specific module
|
|
python3 -m pytest tests/test_hashing.py
|
|
```
|
|
|
|
### Dependencies
|
|
Dependencies are listed in `requirements.txt`. Install with:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Code Architecture
|
|
|
|
### Module Structure
|
|
- **salt.py**: Core module containing `hash_password()` and `verify_password()` functions, plus an integrated CLI via `main()`
|
|
- **salt2.py**: Wrapper CLI that imports from `salt.py` and provides an alternative command structure
|
|
- **tests/**: Test suite mirroring the module structure
|
|
- `test_hashing.py`: Tests for core hashing/verification functions
|
|
- `test_cli.py`: Tests for CLI behavior (specifically `salt.py`'s shortcut syntax)
|
|
|
|
### Key Functions
|
|
|
|
**`hash_password(password, *, iterations=None, salt_bytes=16) -> tuple[str, str]`**
|
|
- Generates a cryptographically secure random salt
|
|
- Derives a hash using PBKDF2-HMAC-SHA256
|
|
- Returns base64-encoded (salt, hash) tuple
|
|
|
|
**`verify_password(password, salt_b64, hash_b64, *, iterations=None) -> bool`**
|
|
- Validates a password against stored salt/hash
|
|
- Uses timing-safe comparison via `hmac.compare_digest()`
|
|
- Returns `False` for invalid base64 without raising exceptions
|
|
|
|
### CLI Argument Handling
|
|
The `salt.py` module includes `_normalize_args()` which allows shortcut syntax: if the first argument is not a subcommand (`hash`/`verify`) and not a flag, it's automatically prefixed with `hash`. This is tested in `tests/test_cli.py:test_main_supports_hash_shortcut()`.
|
|
|
|
## Development Guidelines
|
|
|
|
### Python Version and Style
|
|
- Target Python 3.11+
|
|
- Use type annotations on public functions
|
|
- 4-space indentation
|
|
- Follow `lowercase_with_underscores` naming for functions and variables
|
|
|
|
### Security Practices
|
|
- Always use `os.urandom()` for salt generation (never predictable values)
|
|
- Use `hmac.compare_digest()` for hash comparison to prevent timing attacks
|
|
- Validate base64 input with `validate=True` parameter
|
|
- Handle encoding errors gracefully by returning `False` rather than raising exceptions
|
|
|
|
### Testing Requirements
|
|
- Place tests in `tests/test_<module>.py` matching the module name
|
|
- Cover happy paths and error handling (invalid base64, wrong passwords)
|
|
- Include round-trip tests: hash → verify with correct/incorrect passwords
|
|
- Maintain >90% coverage for hashing utilities
|
|
- When adding new hash algorithms, include regression tests with known salt/hash pairs
|
|
|
|
### Configuration
|
|
- Iteration count defaults to 200,000 but respects `PBKDF2_ITERATIONS` environment variable
|
|
- Salt size defaults to 16 bytes (configurable via `salt_bytes` parameter)
|
|
|
|
## Commit Guidelines
|
|
|
|
Use imperative subject lines with conventional commit prefixes:
|
|
- `feat:` for new features
|
|
- `fix:` for bug fixes
|
|
- `test:` for test additions/changes
|
|
- `refactor:` for code restructuring
|
|
|
|
Reference issues with `Fixes #ID` when applicable. PRs should only be opened after tests pass.
|