fleche.security
===============

.. py:module:: fleche.security


Attributes
----------

.. autoapisummary::

   fleche.security.logger


Exceptions
----------

.. autoapisummary::

   fleche.security.SignatureError


Classes
-------

.. autoapisummary::

   fleche.security.SignedBytes


Functions
---------

.. autoapisummary::

   fleche.security.normalize_secret_key
   fleche.security.get_secret_key


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

.. py:data:: logger

.. py:exception:: SignatureError

   Bases: :py:obj:`Exception`


   Exception raised when signature verification fails.


.. py:function:: normalize_secret_key(key) -> list[bytes]

   Normalize a secret key value to ``list[bytes]``.

   Accepts:
   - ``bytes``: wrapped in a list
   - ``str``: interpreted as a hex-encoded key; colon (``:``) separates multiple keys
   - ``list[bytes]``: each element used as-is
   - ``list[str]``: each element interpreted as hex-encoded; colon-delimited parts
     within an element are treated as separate keys

   This is the single normalization path used by both the ``FLECHE_SECRET_KEY``
   environment variable and programmatic ``secret_key`` arguments — so any key
   that can be expressed in the environment variable can also be passed directly,
   and vice-versa.

   :raises TypeError: if ``key`` or any list element is not ``bytes`` or ``str``
   :raises ValueError: if any string part is not valid hex


.. py:function:: get_secret_key() -> list[bytes]

   Retrieve the secret key(s) from the ``FLECHE_SECRET_KEY`` environment variable.

   The value must be a colon-separated list of hex-encoded byte strings.
   Returns an empty list if the environment variable is not set (security disabled).

   Uses the same :func:`normalize_secret_key` logic as the programmatic API,
   so any value valid here is also valid as a ``secret_key`` argument and
   vice-versa.

   :returns: A list of secret keys as bytes.
   :rtype: list[bytes]


.. py:class:: SignedBytes

   Helper class to sign and verify serialized data using HMAC-SHA256.
   Allows for key rotation by accepting a list of keys.

   :param keys: A list of secret keys. The first key is used for signing,
                and all keys are attempted during verification.
   :type keys: list[bytes]


   .. py:attribute:: keys
      :type:  list[bytes]


   .. py:method:: _sign(data: bytes, key: bytes) -> bytes

      Generate HMAC-SHA256 hex signature for data using the specified key.
      Hex encoding ensures the signature string (0-9a-f) never contains
      the pickle STOP opcode byte (ASCII 46, `.`).

      :param data: The data to sign.
      :type data: bytes
      :param key: The secret key to use for signing.
      :type key: bytes

      :returns: The resulting 64-byte hex-encoded HMAC signature.
      :rtype: bytes



   .. py:method:: dumps(content: bytes) -> bytes

      Signs the content using the first key in the list and appends the hex signature.
      If no keys are provided, returns the content unmodified.

      :param content: The serialized data to sign.
      :type content: bytes

      :returns: The original data with the 64-byte hex signature appended (if keys exist).
      :rtype: bytes



   .. py:method:: loads(content: bytes) -> bytes

      Verifies the signature of the content.
      Extracts the signature by searching for the pickle STOP opcode.
      Iterates through all provided keys for verification.
      Returns the original content if verification passes.

      :param content: The payload containing the data and the appended signature.
      :type content: bytes

      :returns: The original serialized data, stripped of the signature.
      :rtype: bytes

      :raises SignatureError: If verification fails, if the data is corrupted, or if the
          STOP opcode is missing.