xtrace_sdk.x_vec.crypto.key_provider
====================================

.. py:module:: xtrace_sdk.x_vec.crypto.key_provider

.. autoapi-nested-parse::

   Key provider abstractions for AES key management.

   Defines a ``KeyProvider`` protocol and concrete implementations:

   - ``PassphraseKeyProvider``: derives a 256-bit AES key from a passphrase using scrypt.
   - ``AWSKMSKeyProvider``: envelope encryption via AWS KMS — the data encryption key (DEK)
     is generated or unwrapped by KMS and never persisted in plaintext.



Attributes
----------

.. autoapisummary::

   xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_N
   xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_R
   xtrace_sdk.x_vec.crypto.key_provider._SCRYPT_P
   xtrace_sdk.x_vec.crypto.key_provider._KEY_LEN
   xtrace_sdk.x_vec.crypto.key_provider._DEFAULT_SALT


Classes
-------

.. autoapisummary::

   xtrace_sdk.x_vec.crypto.key_provider.KeyProvider
   xtrace_sdk.x_vec.crypto.key_provider.PassphraseKeyProvider
   xtrace_sdk.x_vec.crypto.key_provider.AWSKMSKeyProvider


Module Contents
---------------

.. py:data:: _SCRYPT_N
   :value: 16384


.. py:data:: _SCRYPT_R
   :value: 8


.. py:data:: _SCRYPT_P
   :value: 1


.. py:data:: _KEY_LEN
   :value: 32


.. py:data:: _DEFAULT_SALT
   :value: b'xtrace-aes-gcm-v1'


.. py:class:: KeyProvider

   Bases: :py:obj:`Protocol`


   Protocol for objects that supply a 256-bit AES key and can wrap/unwrap it for storage.


   .. py:method:: get_key()

      Return the raw 256-bit AES key.



   .. py:method:: wrap_key()

      Return an opaque blob that can be stored alongside ciphertext to recover the key later.



   .. py:method:: from_wrapped(wrapped, **kwargs)
      :classmethod:


      Reconstruct a provider from a blob previously returned by :meth:`wrap_key`.



   .. py:method:: provider_id()

      Return a short identifier for the provider type (used in serialization).



.. py:class:: PassphraseKeyProvider(passphrase, salt = None)

   Derives a 256-bit AES key from a passphrase using scrypt.

   This is the default key provider and preserves backwards-compatible behavior.
   The passphrase is never stored — only the derived key is kept in memory.


   .. py:attribute:: _salt
      :value: b'xtrace-aes-gcm-v1'



   .. py:attribute:: _key


   .. py:method:: get_key()


   .. py:method:: wrap_key()


   .. py:method:: from_wrapped(wrapped, **kwargs)
      :classmethod:


      Re-derive the key from the passphrase and stored salt.

      :param wrapped: The salt bytes returned by :meth:`wrap_key`.
      :param passphrase: The original passphrase (passed via kwargs).



   .. py:method:: provider_id()


.. py:class:: AWSKMSKeyProvider(kms_client, key_id)

   Envelope encryption via AWS KMS.

   On creation, generates a random 256-bit DEK and wraps it with KMS.
   On load, unwraps a previously wrapped DEK using KMS.

   Requires ``boto3`` at runtime. The KMS key must grant the caller
   ``kms:Encrypt`` and ``kms:Decrypt`` permissions.

   :param kms_client: A ``boto3`` KMS client (``boto3.client("kms")``).
   :param key_id: KMS key ID, ARN, or alias (e.g. ``"alias/xtrace"``).


   .. py:attribute:: _kms


   .. py:attribute:: _key_id


   .. py:attribute:: _key
      :type:  bytes | None
      :value: None



   .. py:attribute:: _edek
      :type:  bytes | None
      :value: None



   .. py:method:: create(kms_client, key_id)
      :classmethod:


      Generate a fresh DEK via KMS ``GenerateDataKey``.

      :param kms_client: A ``boto3`` KMS client.
      :param key_id: KMS key ID, ARN, or alias.



   .. py:method:: from_wrapped(wrapped, **kwargs)
      :classmethod:


      Unwrap a previously stored EDEK using KMS ``Decrypt``.

      :param wrapped: The EDEK bytes returned by :meth:`wrap_key`.
      :param kms_client: A ``boto3`` KMS client (passed via kwargs).
      :param key_id: KMS key ID, ARN, or alias (passed via kwargs).



   .. py:method:: get_key()


   .. py:method:: wrap_key()


   .. py:method:: provider_id()