Introduce keystore encryption wrapper

[strawgate]

Let's make a second version of the encryption wrapper which generates a key and stores it in the system keychain

[github-actions]

Claude finished @strawgate's task in 2m 28s —— View job

---

Recommendation

Create a new KeyringEncryptionWrapper that extends BaseEncryptionWrapper and uses KeyringStore to automatically generate and persist Fernet encryption keys in the system keychain. This follows the existing patterns in the codebase and leverages two already-implemented components.

Findings

Existing Components

The codebase already has:

1. BaseEncryptionWrapper (src/key_value/aio/wrappers/encryption/base.py) - Abstract encryption wrapper that accepts encryption_fn and decryption_fn callbacks
2. FernetEncryptionWrapper (src/key_value/aio/wrappers/encryption/fernet.py) - Fernet implementation that accepts either a Fernet/MultiFernet instance or source_material/salt pair
3. KeyringStore (src/key_value/aio/stores/keyring/store.py) - Backend that uses Python's keyring library for system keychain storage

Proposed Design

The new KeyringEncryptionWrapper would:

• Generate a Fernet key using Fernet.generate_key() on first use
• Store the key in the system keychain using keyring.set_password()
• Retrieve the key on subsequent initializations using keyring.get_password()
• Support key rotation via MultiFernet with optional old keys parameter
• Use a configurable service name and username for keychain storage

This aligns with Fernet best practices of using secure key storage and supports key rotation patterns.

Detailed Action Plan

1. Create the new wrapper module

File: src/key_value/aio/wrappers/encryption/keyring.py

"""Keyring-based encryption wrapper that stores keys in the system keychain."""

import keyring
from cryptography.fernet import Fernet, MultiFernet

from key_value.aio.protocols.key_value import AsyncKeyValue
from key_value.aio.wrappers.encryption.base import BaseEncryptionWrapper
from key_value.shared.errors import EncryptionVersionError

ENCRYPTION_VERSION = 1
DEFAULT_SERVICE_NAME = "py-key-value-encryption"
DEFAULT_KEY_NAME = "encryption-key"


class KeyringEncryptionWrapper(BaseEncryptionWrapper):
    """Wrapper that encrypts values using a Fernet key stored in the system keychain.

    This wrapper automatically generates and stores an encryption key in the system
    keychain on first use. Subsequent instantiations with the same service_name and
    key_name will retrieve the existing key.
    """

    def __init__(
        self,
        key_value: AsyncKeyValue,
        *,
        service_name: str = DEFAULT_SERVICE_NAME,
        key_name: str = DEFAULT_KEY_NAME,
        old_keys: list[bytes] | None = None,
        raise_on_decryption_error: bool = True,
    ) -> None:
        """Initialize the keyring encryption wrapper.

        Args:
            key_value: The key-value store to wrap.
            service_name: The service name for keychain storage.
            key_name: The username/key name for keychain storage.
            old_keys: Optional list of old Fernet keys for rotation support.
            raise_on_decryption_error: Whether to raise on decryption failure.
        """
        self._service_name = service_name
        self._key_name = key_name

        # Get or generate the encryption key
        key_str = keyring.get_password(service_name=service_name, username=key_name)
        if key_str is None:
            key = Fernet.generate_key()
            keyring.set_password(service_name=service_name, username=key_name, password=key.decode("ascii"))
        else:
            key = key_str.encode("ascii")

        # Build Fernet with optional old keys for rotation
        if old_keys:
            fernets = [Fernet(key)] + [Fernet(old_key) for old_key in old_keys]
            fernet: Fernet | MultiFernet = MultiFernet(fernets)
        else:
            fernet = Fernet(key)

        def encrypt_with_fernet(data: bytes) -> bytes:
            return fernet.encrypt(data)

        def decrypt_with_fernet(data: bytes, encryption_version: int) -> bytes:
            if encryption_version > ENCRYPTION_VERSION:
                msg = f"Decryption failed: encryption versions newer than {ENCRYPTION_VERSION} are not supported"
                raise EncryptionVersionError(msg)
            return fernet.decrypt(data)

        super().__init__(
            key_value=key_value,
            encryption_fn=encrypt_with_fernet,
            decryption_fn=decrypt_with_fernet,
            encryption_version=ENCRYPTION_VERSION,
            raise_on_decryption_error=raise_on_decryption_error,
        )

2. Update exports

File: src/key_value/aio/wrappers/encryption/__init__.py

Add the new wrapper to the exports:

from key_value.aio.wrappers.encryption.base import BaseEncryptionWrapper
from key_value.aio.wrappers.encryption.fernet import FernetEncryptionWrapper
from key_value.aio.wrappers.encryption.keyring import KeyringEncryptionWrapper

__all__ = ["BaseEncryptionWrapper", "FernetEncryptionWrapper", "KeyringEncryptionWrapper"]

3. Add tests

File: tests/stores/wrappers/test_encryption_keyring.py

Create tests that:

• Verify key generation on first use
• Verify key retrieval on subsequent use
• Test encryption/decryption round-trip
• Test key rotation with old_keys parameter
• Test wrong key detection
• Test platform-specific behavior (macOS/Windows keychain)

Use the existing BaseStoreTests mixin pattern from tests/stores/wrappers/test_encryption.py.

4. Update documentation

File: docs/wrappers.md

Add a section for KeyringEncryptionWrapper explaining:

• Auto-generated key storage in system keychain
• Service name and key name configuration
• Key rotation support
• Security considerations

5. Update optional dependencies (if needed)

The wrapper requires both keyring and cryptography. Consider adding a combined extra:

wrappers-encryption-keyring = ["keyring>=25.6.0", "cryptography>=45.0.0"]

Related Files

Repository	File	Relevance	Sections
strawgate/py-key-value	src/key_value/aio/wrappers/encryption/base.py	Base class to extend for the new wrapper	Lines 20-54
strawgate/py-key-value	src/key_value/aio/wrappers/encryption/fernet.py	Reference implementation showing Fernet usage pattern	Lines 13-89
strawgate/py-key-value	src/key_value/aio/stores/keyring/store.py	Reference for keyring library usage patterns	Lines 55-141
strawgate/py-key-value	tests/stores/wrappers/test_encryption.py	Test patterns to follow for the new wrapper	Full file

Related Webpages

Name	URL	Relevance
Fernet Documentation	https://cryptography.io/en/latest/fernet/	Official Fernet documentation including key generation and rotation
Python Keyring Library	https://pypi.org/project/keyring/	Documentation for the keyring library used for system keychain access

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@claude make a PR please

[github-actions]

Claude encountered an error —— View job • claude/issue-293-20260203-0844 • Create PR ➔

---

KeyringEncryptionWrapper PR Created

• Gather repository context and understand existing patterns
• Create KeyringEncryptionWrapper class
• Update exports in __init__.py
• Add tests for the new wrapper
• Run linting and type checking
• Run tests
• Commit and push changes
• Create PR

Summary

Created a new KeyringEncryptionWrapper that stores encryption keys in the system keychain:

New Files:

• src/key_value/aio/wrappers/encryption/keyring.py - The wrapper implementation
• tests/stores/wrappers/test_encryption_keyring.py - Comprehensive test suite

Key Features:

• Auto-generates Fernet encryption keys on first use
• Retrieves existing keys on subsequent instantiations
• Configurable service_name and key_name for keychain storage
• Supports key rotation via old_keys parameter
• Follows existing FernetEncryptionWrapper patterns

--- |

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.