Implement HashiCorp Vault integration

[vpuhoff]

This commit introduces significant new functionality by adding support for HashiCorp Vault secret fetching and completely refactors the library's error handling mechanisms for improved robustness and clarity. Documentation and tests have been updated accordingly.

Key Changes:

1. HashiCorp Vault Integration:

   • Introduced a new !VAULT YAML tag, allowing users to seamlessly fetch secrets directly from HashiCorp Vault within their YAML configuration files.
   • Implemented vault_constructor for the YAML loader to process the !VAULT tag, handling path and key parsing.
   • Added _get_vault_client helper function for robust Vault client initialization, including authentication using VAULT_TOKEN.
   • Configuration for Vault access is managed via VAULT_ADDR and VAULT_TOKEN environment variables.
   • The hvac library has been added as a new core dependency for Vault communication.

2. Explicit Error Handling with Custom Exceptions:

   • Core library functions (including _load_fernet_key, _get_vault_client, encrypt_string_value, load_yaml_secrets, YAML tag constructors like sec_constructor & vault_constructor, and sec_representer in the dumper) have been refactored.
   • These functions now raise specific, custom exceptions (e.g., KeylockerFileError, KeylockerEncryptionError, KeylockerConfigError, KeylockerVaultError, VaultClientNotInitializedError, VaultKeyNotFoundError, VaultInvalidPathError) instead of printing error messages and returning None or directly calling sys.exit(). This makes the library's error contract clearer and facilitates better error handling by calling code.
   • A bug in vault_constructor was fixed where custom exceptions like VaultKeyNotFoundError were being incorrectly caught and re-wrapped by a generic except Exception block. The try-except structure within vault_constructor has been refined for correct propagation of specific custom exceptions.

3. CLI Enhancements (Manager class):

   • The CLI command methods (view, encrypt) within the Manager class have been updated to catch the newly introduced specific exceptions from the core library functions.
   • These CLI methods now output user-friendly error messages to stderr and exit with appropriate non-zero status codes, adhering to standard CLI best practices.

4. Testing (pytest):

   • A new suite of pytest unit tests (tests/test_keylocker_vault.py) has been developed to cover the HashiCorp Vault integration, including various success and failure scenarios.
   • Existing unit tests for Fernet key management, !SEC tag processing, and !ENV tag resolution (tests/test_keylocker_yaml.py) have been updated and refactored to align with the new exception-based error handling paradigm (e.g., using pytest.raises to assert specific exceptions).
   • Minor issues in test setup, such as missing imports (e.g., Fernet in test files), have been resolved.

5. Documentation (README.md):

   • The README.md file has been extensively updated to accurately reflect all new features and significant changes.
   • Comprehensive documentation for the HashiCorp Vault integration has been added, including details on the !VAULT tag syntax and the required VAULT_ADDR and VAULT_TOKEN environment variables.
   • Python code usage examples in README.md have been revised to demonstrate best practices for try-except blocks to handle the new specific KeylockerError exceptions.
   • Bash usage examples have also been updated.
   • The entire README.md content has been translated into English.

6. Dependencies:

   • hvac has been added to requirements.txt as a runtime dependency.
   • pytest and pytest-mock are confirmed as development dependencies for the test suite.