feat: challenge-response providers with KEK multi-device support

[coreyleavitt]

Summary

Implements hardware-backed challenge-response authentication with KEK (Key Encryption Key) wrapping to enable multiple devices to unlock the same database. Based on PR #63 discussion.

Two operating modes:

• Legacy mode: CR mixed into composite key (KeePassXC-compatible, YubiKey HMAC-SHA1 only)
• KEK mode: CR used to wrap/unwrap KEK (multi-device, any provider type)

Key changes:

• Add ChallengeResponseProvider Protocol for structural typing
• Add YubiKeyHmacSha1 for KeePassXC-compatible HMAC-SHA1
• Add Fido2HmacSecret ABC with YubiKeyFido2 implementation
• Add KEK wrapping module (security/kek.py) for multi-device support
• Add device enrollment API: enroll_device(), revoke_device(), list_enrolled_devices()
• Add testing module with MockYubiKey, MockFido2, MockProvider
• Store enrolled devices in header CustomData with AES-256-GCM wrapped KEKs

Design Decisions

1. KEK mode is default for all enrollments (even single-device)
2. Legacy mode opt-in only for explicit KeePassXC/KeePassDX compatibility
3. FIDO2 always uses KEK mode - 32-byte responses rejected in legacy mode
4. Cannot mix legacy and KEK modes on same database
5. Protocol not ABC for ChallengeResponseProvider - allows third-party implementations
6. Mocks in testing module - NOT in security/ to avoid implying they're secure

KEK Architecture

Legacy Mode (KeePassXC-compatible):
  Password + Keyfile + CR_Response → Composite Key → KDF → Master Key

KEK Mode (multi-device):
  Password + Keyfile → Composite Key → KDF → Base Master Key
  Device CR → Unwrap KEK → Base Master ⊕ KEK → Final Master Key

Each enrolled device wraps the same KEK with its unique CR output (AES-256-GCM).

New Public API

from kdbxtool import (
    ChallengeResponseProvider,  # Protocol
    YubiKeyHmacSha1,            # YubiKey HMAC-SHA1 (KeePassXC-compatible)
    YubiKeyFido2,               # YubiKey FIDO2 hmac-secret
)
from kdbxtool.testing import MockYubiKey, MockFido2  # For testing

# KEK mode (recommended) - supports multiple devices
db = Database.create(password="secret")
db.enroll_device(yubikey, label="Primary YubiKey")
db.enroll_device(fido2, label="Backup FIDO2")
db.save("vault.kdbx")

# Either device can open
db = Database.open("vault.kdbx", password="secret", challenge_response_provider=yubikey)
db = Database.open("vault.kdbx", password="secret", challenge_response_provider=fido2)

# Legacy mode (KeePassXC compatible, single YubiKey only)
db.save("vault.kdbx", challenge_response_provider=yubikey)

Test plan

• All existing tests pass (806 passed, 12 skipped, 5 xfailed)
• KEK wrap/unwrap unit tests (43 tests)
• Device enrollment API tests
• KEK mode roundtrip tests
• Mixed YubiKey + FIDO2 enrollment tests
• Legacy mode rejection of FIDO2 (32-byte responses)
• Hardware testing with YubiKey (manual)
• Type checking with mypy

[coreyleavitt]

Hardware Key Testing Instructions

This PR adds KEK (Key Encryption Key) wrapping for multi-device challenge-response support. To verify the implementation, hardware testing with a physical YubiKey is required.

Prerequisites

• YubiKey with HMAC-SHA1 configured in slot 2
• Configure with: ykman otp chalresp --generate 2

Running Hardware Tests

# Run all hardware tests (22 tests total)
pytest -m hardware tests/test_hardware_keys.py -v

# With specific YubiKey serial
YUBIKEY_SERIAL=12345678 pytest -m hardware -v

Test Coverage

Test Class	Mode	Tests
TestYubiKeyHardware	N/A	6 low-level provider tests
TestDatabaseYubiKeyHardware	Legacy	5 database integration tests
TestKekModeHardware	KEK	9 multi-device enrollment tests
TestKeePassXCCompatibility	Both	2 format compatibility tests

KEK Mode Tests (TestKekModeHardware)

• test_enroll_single_device - Single device enrollment
• test_enroll_device_bytes_roundtrip - Serialization roundtrip
• test_modify_and_resave_kek_mode - Modify and resave workflow
• test_wrong_password_kek_mode - Wrong password rejection
• test_missing_device_kek_mode - Missing device rejection
• test_list_enrolled_devices - Device listing
• test_disable_kek_mode_migration - Migration to password-only
• test_rotate_kek - KEK rotation
• test_revoke_device_prevents_access - Device revocation

Expected Results

Without hardware: All 22 tests will be skipped with "No YubiKey connected"

With hardware: All 22 tests should pass

KeePassXC Compatibility Testing (Manual)

To verify legacy mode compatibility:

1. Create a database with kdbxtool in legacy mode:

from kdbxtool import Database, YubiKeyHmacSha1

db = Database.create(password="testpassword")
db.root_group.create_entry(title="Test", username="user", password="pass")
db.save("test.kdbx", challenge_response_provider=YubiKeyHmacSha1(slot=2))

2. Open in KeePassXC with the same YubiKey
3. Verify the entry is accessible

See tests/HARDWARE_TESTING.md for the complete testing guide.