.. core-auth documentation master file, created by
   sphinx-quickstart on Mon Mar 31 19:45:23 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

core-auth
===============================================================================

This project/library contains common elements related to
authentication & authorization...

===============================================================================

.. image:: https://img.shields.io/pypi/pyversions/core-auth.svg
    :target: https://pypi.org/project/core-auth/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-auth/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-auth/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-auth/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-auth/badge/?version=latest
    :target: https://readthedocs.org/projects/core-auth/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security



Documentation Contents
-------------------------------------------------------------------------------

.. toctree::
   :maxdepth: 1
   :caption: Index:

   jwt_token


Features
-------------------------------------------------------------------------------

* **JWT Token Wrapper** - Simplified interface for JSON Web Token operations
* **Multiple Cryptographic Algorithms** - Support for HMAC (HS256, HS384, HS512), RSA (RS256, RS384, RS512, PS256, PS384, PS512), ECDSA (ES256, ES256K, ES384, ES512), and EdDSA algorithms
* **Token Encoding** - Create JWT tokens with customizable claims, headers, and expiration times
* **Token Decoding & Validation** - Decode and verify JWT tokens with comprehensive validation options (signature, expiration, audience, issuer, etc.)
* **Authorization Header Parsing** - Extract Bearer tokens from HTTP Authorization headers
* **Public/Private Key Support** - Compatible with RSA, Elliptic Curve (EC), Ed25519, and Ed448 key pairs
* **Custom Claims** - Add standardized or custom claims to JWT payloads
* **Type-Safe** - Full type hints support for better IDE integration and code safety


Quick Start
-------------------------------------------------------------------------------

.. code-block:: python

    from core_auth import JwtToken, JwtException, ALGORITHM

    # HMAC (symmetric)
    client = JwtToken(private_key="S3cr3t", expire=3600)
    token = client.encode(subject="user-123", claims={"iss": "my-service"})

    payload = client.decode(token, issuer="my-service")
    print(payload["sub"])  # "user-123"

    # Asymmetric (RSA, ECDSA, EdDSA) — keys loaded from PEM files
    private_pem = open("tests/resources/private.pem").read()
    public_pem = open("tests/resources/public.pem").read()
    client = JwtToken(private_key=private_pem, public_key=public_pem)
    token = client.encode(subject="user-123", algorithm=ALGORITHM.RS256)
    payload = client.decode(token, algorithms=[ALGORITHM.RS256])
    print(payload["sub"])

    # Parse an HTTP Authorization header
    raw_token = JwtToken.from_auth_header("Bearer eyJ...")

    # Handle errors
    try:
        client.decode("invalid.token")
    except JwtException as exc:
        print(exc)  # "Invalid token."

See the :doc:`jwt_token` page for the full API reference and more examples.


Installation
-------------------------------------------------------------------------------

Install from PyPI using pip:

.. code-block:: bash

    pip install core-auth
    uv pip install core-auth    # Or using UV...
    pip install -e ".[dev]"     # For development...


Setting Up Environment
-------------------------------------------------------------------------------

1. Install required libraries:

.. code-block:: bash

    pip install --upgrade pip
    pip install virtualenv

2. Create Python virtual environment:

.. code-block:: bash

    virtualenv --python=python3.12 .venv

3. Activate the virtual environment:

.. code-block:: bash

    source .venv/bin/activate

Install packages
-------------------------------------------------------------------------------

.. code-block:: bash

    pip install .
    pip install -e ".[dev]"

Check tests and coverage
-------------------------------------------------------------------------------

.. code-block:: shell

    python manager.py run-tests
    python manager.py run-coverage


Contributing
-------------------------------------------------------------------------------

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: ``pytest -n auto``
5. Run linting: ``pylint core_auth``
6. Run security checks: ``bandit -r core_auth``
7. Submit a pull request


License
-------------------------------------------------------------------------------

This project is licensed under the MIT License. See the LICENSE file for details.


Links
-------------------------------------------------------------------------------

* **Documentation:** https://core-auth.readthedocs.io/en/latest/
* **Repository:** https://gitlab.com/bytecode-solutions/core/core-auth
* **Issues:** https://gitlab.com/bytecode-solutions/core/core-auth/-/issues
* **Changelog:** https://gitlab.com/bytecode-solutions/core/core-auth/-/blob/master/CHANGELOG.md
* **PyPI:** https://pypi.org/project/core-auth/


Support
-------------------------------------------------------------------------------

For questions or support, please open an issue on GitLab or contact the maintainers.


Authors
-------------------------------------------------------------------------------

* **Alejandro Cora González** - *Initial work* - alek.cora.glez@gmail.com