Implement KeyGuard 4.0: complete rewrite with v3→v4 migration

[Crypt-Guard]

Summary

This is a complete rewrite of KeyGuard, introducing version 4.0 with a modern architecture, improved security practices, and seamless migration from legacy v3 vaults. The codebase has been restructured into modular components with clear separation of concerns: cryptography, storage, vault management, UI, and utilities.

Key Changes

Core Architecture

• New modular structure: Separated concerns into crypto/, storage/, vault/, ui/, and util/ packages
• VaultManager: High-level CRUD operations with support for both v3 (legacy) and v4 (current) vault formats
• StorageBackend: Atomic writes, backup/restore, cross-platform file locking, and permission management
• CryptoEngine: Unified cryptographic operations (Argon2id KDF, ChaCha20-Poly1305 AEAD, HMAC-SHA256)

Security Enhancements

• Secure memory management (SecureMemory): Multi-pass wipe, platform-specific memory locking (mlock/VirtualLock), and obfuscation
• KeyObfuscator: In-memory key obfuscation with XOR-based masking to prevent direct memory inspection
• TimedExposure: Context manager for controlled, time-limited key exposure during cryptographic operations
• PasswordTimeout: Automatic session timeout with secure memory cleanup
• RateLimiter: Exponential backoff protection against brute-force attacks
• Platform hardening: OS-level protections (DEP, core dump disabling, process isolation)

Vault Format Evolution

• v3→v4 migration: Automatic transparent migration when opening legacy v3 vaults
• Self-descriptive v4 header: KDF parameters (time cost, memory cost, parallelism) stored in vault header for reproducible key derivation
• Configurable KDF profiles: compat (64 MiB), balanced (256 MiB), high (512 MiB) with security floor enforcement
• Protocol versioning: Magic bytes (KG3/KG4) and version fields for format detection

UI & UX

• Tkinter/ttkbootstrap GUI: Modern, responsive interface with password generation and vault viewing
• Secure dialogs: Password input dialogs that return SecureMemory objects, never plain strings
• Password generator: Configurable charset selection with entropy calculation and strength visualization
• Vault viewer: Browse, add, edit, and delete entries with secure display toggling

Configuration & Paths

• Centralized Config: Single source of truth for security parameters, UI settings, and KDF profiles
• Cross-platform paths: XDG-compliant on Linux, standard locations on Windows/macOS with legacy migration support
• Secure logging: Sanitised formatter that redacts sensitive data (bytes, long strings) from logs

Testing

• Comprehensive test suite covering:
  • Vault header serialisation (v3 and v4)
  • Roundtrip encryption/decryption
  • v3→v4 migration
  • Secure memory handling
  • Cryptographic operations
  • Storage atomicity and backup
  • Rate limiting and password generation

Notable Implementation Details

• Memory safety: All sensitive data (passwords, keys) stored in SecureMemory with guaranteed cleanup
• Atomic vault writes: Temporary file + rename pattern with automatic backup on overwrite
• HMAC verification: All vault data authenticated with HMAC-SHA256 to detect tampering
• Deterministic KDF: Argon2id parameters stored in vault header ensure consistent key derivation across versions
• Rate limiting: Exponential backoff (2^attempt seconds) after 5 failed login attempts
• Fragmented secrets: Optional secret splitting for enhanced security (not yet exposed in UI)
• CI/CD: GitHub Actions workflow for multi-platform testing (Ubuntu, Windows; Python 3.9–3.12)

Migration Path

Users with existing v3 vaults can seamlessly upgrade: opening a v3 vault automatically migrates it to v4 format with

https://claude.ai/code/session_01QFXUR2eEwC6mUgrQjMEQ6S