flip_api.utils.encryption
=========================

.. py:module:: flip_api.utils.encryption


Attributes
----------

.. autoapisummary::

   flip_api.utils.encryption._aes_key_cache


Functions
---------

.. autoapisummary::

   flip_api.utils.encryption.get_aes_key
   flip_api.utils.encryption.encrypt
   flip_api.utils.encryption.decrypt


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

.. py:data:: _aes_key_cache
   :type:  bytes | None
   :value: None


.. py:function:: get_aes_key() -> bytes

   Retrieve the AES key and return it as bytes.

   In production, fetches from AWS Secrets Manager. In dev, uses the environment variable directly.
   Cached after first call — the key does not change during the lifetime of a process.

   :returns: The decoded AES key.
   :rtype: bytes


.. py:function:: encrypt(plaintext: str, key: bytes | None = None) -> str

   Encrypt plaintext using AES-CBC with PKCS7 padding. Returns Base64-encoded ciphertext.

   :param plaintext: The plaintext string to encrypt.
   :type plaintext: str
   :param key: The AES key to use. If None, the shared AES key is retrieved via
               :func:`get_aes_key`.
   :type key: bytes | None

   :returns: Base64-encoded ciphertext, with the random IV prepended to the ciphertext bytes
             before encoding.
   :rtype: str


.. py:function:: decrypt(encoded_payload: str, key: bytes | None = None) -> str

   Decrypt Base64-encoded ciphertext using AES-CBC with PKCS7 padding. Returns the original plaintext.

   :param encoded_payload: Base64-encoded payload where the first 16 bytes are the IV and the
                           remaining bytes are the ciphertext.
   :type encoded_payload: str
   :param key: The AES key to use. If None, the shared AES key is retrieved via
               :func:`get_aes_key`.
   :type key: bytes | None

   :returns: The decrypted plaintext.
   :rtype: str