corvix.crypto
=============

.. py:module:: corvix.crypto

.. autoapi-nested-parse::

   Fernet-based token encryption helpers and SQLAlchemy encrypted column type.



Classes
-------

.. autoapisummary::

   corvix.crypto.EncryptedText


Functions
---------

.. autoapisummary::

   corvix.crypto.get_fernet
   corvix.crypto.encrypt_token
   corvix.crypto.decrypt_token


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

.. py:function:: get_fernet() -> cryptography.fernet.Fernet

   Return a Fernet instance keyed from the TOKEN_ENCRYPTION_KEY env var.

   Raises:
       RuntimeError: if TOKEN_ENCRYPTION_KEY (or TOKEN_ENCRYPTION_KEY_FILE) is not set.


.. py:function:: encrypt_token(plaintext: str) -> str

   Encrypt a plaintext token string with Fernet symmetric encryption.

   Returns:
       A URL-safe base64-encoded Fernet token (starts with ``gAAAAA``).


.. py:function:: decrypt_token(ciphertext: str) -> str

   Decrypt a Fernet-encrypted token string back to plaintext.

   Raises:
       cryptography.fernet.InvalidToken: if the ciphertext is invalid or the key is wrong.


.. py:class:: EncryptedText(*args: Any, **kwargs: Any)

   Bases: :py:obj:`sqlalchemy.types.TypeDecorator`


   SQLAlchemy column type that transparently Fernet-encrypts values at rest.

   The database column stores a URL-safe base64 Fernet token (plain TEXT).
   Python code reads and writes the original plaintext string.

   Requires the TOKEN_ENCRYPTION_KEY environment variable (or TOKEN_ENCRYPTION_KEY_FILE
   for Docker secret file support) to be set at application startup and during migrations.


   .. py:attribute:: impl


   .. py:attribute:: cache_ok
      :value: True


      Marks this type as safe to use with SQLAlchemy's statement cache.



   .. py:method:: process_bind_param(value: str | None, dialect: object) -> str | None

      Encrypt the Python value before writing it to the database.



   .. py:method:: process_result_value(value: str | None, dialect: object) -> str | None

      Decrypt the database value when loading it into Python.