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:

BaseEncryptionWrapper (src/key_value/aio/wrappers/encryption/base.py) - Abstract encryption wrapper that accepts encryption_fn and decryption_fn callbacks
FernetEncryptionWrapper (src/key_value/aio/wrappers/encryption/fernet.py) - Fernet implementation that accepts either a Fernet/MultiFernet instance or source_material/salt pair
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.

Uh oh!

Introduce keystore encryption wrapper #293

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions