# CLAUDE.md

Diese Datei bietet Anleitungen für Claude Code (claude.ai/code) bei der Arbeit mit Code in diesem Repository.

## Projektübersicht

Dies ist ein Python PBKDF2 Passwort-Hashing-Tool mit zwei Implementierungen:
- `salt.py`: Referenzimplementierung mit CLI, die sowohl `hash` als auch `verify` Unterbefehle unterstützt, plus eine Abkürzung, bei der `python3 salt.py <password>` automatisch den hash-Befehl aufruft
- `salt2.py`: Alternative CLI, die aus `salt.py` importiert und explizite Unterbefehle erfordert (`generate` und `verify`)

Beide Implementierungen verwenden PBKDF2-HMAC-SHA256 mit konfigurierbarer Iterationsanzahl (Standard: 200.000, überschreibbar über die Umgebungsvariable `PBKDF2_ITERATIONS`).

## Häufige Befehle

### CLI ausführen
```bash
# Passwort hashen (salt.py unterstützt Abkürzungssyntax)
python3 salt.py "MeinPasswort"
python3 salt.py hash "MeinPasswort"

# Passwort verifizieren
python3 salt.py verify <passwort> <salt_b64> <hash_b64>

# Alternative CLI (erfordert explizite Unterbefehle)
python3 salt2.py generate "MeinPasswort"
python3 salt2.py verify <passwort> <salt_b64> <hash_b64>
```

### Testen
```bash
# Alle Tests ausführen
python3 -m pytest

# Spezifische Tests mit ausführlicher Ausgabe ausführen
python3 -m pytest -k verify --maxfail=1 -vv

# Tests für ein bestimmtes Modul ausführen
python3 -m pytest tests/test_hashing.py
```

### Abhängigkeiten
Abhängigkeiten sind in `requirements.txt` aufgelistet. Installation mit:
```bash
pip install -r requirements.txt
```

## Code-Architektur

### Modulstruktur
- **salt.py**: Kernmodul mit den Funktionen `hash_password()` und `verify_password()` sowie einer integrierten CLI über `main()`
- **salt2.py**: Wrapper-CLI, die aus `salt.py` importiert und eine alternative Befehlsstruktur bietet
- **tests/**: Test-Suite, die die Modulstruktur widerspiegelt
  - `test_hashing.py`: Tests für Kern-Hashing-/Verifizierungsfunktionen
  - `test_cli.py`: Tests für CLI-Verhalten (speziell die Abkürzungssyntax von `salt.py`)

### Hauptfunktionen

**`hash_password(password, *, iterations=None, salt_bytes=16) -> tuple[str, str]`**
- Generiert ein kryptographisch sicheres zufälliges Salt
- Leitet einen Hash mit PBKDF2-HMAC-SHA256 ab
- Gibt ein base64-kodiertes (Salt, Hash) Tupel zurück

**`verify_password(password, salt_b64, hash_b64, *, iterations=None) -> bool`**
- Validiert ein Passwort gegen gespeichertes Salt/Hash
- Verwendet zeitkonstanten Vergleich über `hmac.compare_digest()`
- Gibt `False` bei ungültigem base64 zurück, ohne Exceptions auszulösen

### CLI-Argumentbehandlung
Das Modul `salt.py` enthält `_normalize_args()`, welches die Abkürzungssyntax ermöglicht: Wenn das erste Argument kein Unterbefehl (`hash`/`verify`) und kein Flag ist, wird automatisch `hash` vorangestellt. Dies wird in `tests/test_cli.py:test_main_supports_hash_shortcut()` getestet.

## Entwicklungsrichtlinien

### Python-Version und Stil
- Ziel-Python-Version: 3.11+
- Typannotationen für öffentliche Funktionen verwenden
- 4-Leerzeichen-Einrückung
- `lowercase_with_underscores` Namenskonvention für Funktionen und Variablen befolgen

### Sicherheitspraktiken
- Immer `os.urandom()` für Salt-Generierung verwenden (niemals vorhersagbare Werte)
- `hmac.compare_digest()` für Hash-Vergleich verwenden, um Timing-Angriffe zu verhindern
- Base64-Eingabe mit `validate=True` Parameter validieren
- Kodierungsfehler elegant behandeln, indem `False` zurückgegeben wird statt Exceptions auszulösen

### Testanforderungen
- Tests in `tests/test_<modul>.py` platzieren, passend zum Modulnamen
- Happy Paths und Fehlerbehandlung abdecken (ungültiges base64, falsche Passwörter)
- Round-Trip-Tests einschließen: hash → verify mit korrekten/inkorrekten Passwörtern
- >90% Coverage für Hashing-Utilities aufrechterhalten
- Bei Hinzufügen neuer Hash-Algorithmen Regressionstests mit bekannten Salt/Hash-Paaren einschließen

### Konfiguration
- Iterationsanzahl standardmäßig 200.000, berücksichtigt aber die Umgebungsvariable `PBKDF2_ITERATIONS`
- Salt-Größe standardmäßig 16 Bytes (konfigurierbar über `salt_bytes` Parameter)

## Commit-Richtlinien

Imperativ formulierte Betreffzeilen mit konventionellen Commit-Präfixen verwenden:
- `feat:` für neue Features
- `fix:` für Fehlerbehebungen
- `test:` für Test-Hinzufügungen/-Änderungen
- `refactor:` für Code-Umstrukturierung

Issues mit `Fixes #ID` referenzieren, wenn zutreffend. PRs sollten erst nach erfolgreichen Tests eröffnet werden.