chore: initial commit with existing codebase

CLAUDE.md

@@ -0,0 +1,104 @@
+# 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.