Metadata-Version: 2.3
Name: jwtifypy
Version: 0.1.0
Summary: Lightweight and extensible Python library for generating and verifying JWT tokens with multiple algorithms (HS256, ES256, RS256, etc.). Built on PyJWT, it provides an intuitive interface, flexible configuration, and secure key storage.
License: MIT
Author: LordCode
Author-email: 9999269010dddd@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Provides-Extra: crypto
Provides-Extra: env
Provides-Extra: full
Requires-Dist: cryptography (>=45.0.5,<46.0.0) ; extra == "crypto" or extra == "full"
Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
Requires-Dist: python-dotenv (>=1.1.1,<2.0.0) ; extra == "env" or extra == "full"
Project-URL: Homepage, https://github.com/lordcod/jwtifypy
Project-URL: Repository, https://github.com/lordcod/jwtifypy
Description-Content-Type: text/markdown

# 🔐 JWTifyPy

**JWTifyPy** — это легковесная и расширяемая Python-библиотека для генерации и проверки JWT-токенов с поддержкой различных алгоритмов (`HS256`, `ES256`, `RS256` и др.).  
Библиотека построена поверх [PyJWT](https://pyjwt.readthedocs.io/) и предоставляет интуитивный интерфейс, удобную конфигурацию и безопасное хранилище ключей — всё, что нужно для работы с JWT.

---

## 📦 Установка

```bash
pip install jwtifypy
````

## ⚙️ Опциональные зависимости

Для работы с переменными окружения (`.env`) и криптографическими алгоритмами (`ES256`) используются дополнительные пакеты: `python-dotenv` и `cryptography`.
Они подключаются как опциональные зависимости и **не устанавливаются по умолчанию**.

Чтобы установить библиотеку с нужными дополнительными пакетами, используйте extras:

* С поддержкой переменных окружения (dotenv):

```bash
pip install jwtifypy[env]
```

* С поддержкой криптографии:

```bash
pip install jwtifypy[crypto]
```

* Полный набор дополнительных возможностей:

```bash
pip install jwtifypy[full]
```

## 🚀 Быстрый старт

### 🔧 Инициализация

```python
from jwtifypy import JWTConfig

JWTConfig.init(config={
    "keys": {
        "algorithm": "HS256",
        "secret": "env:MY_SECRET_ENV"
    }
})
```

### 🪪 Создание токена

```python
from jwtifypy import JWTManager

# 📥 Токен по умолчанию
token = JWTManager().create_access_token("user123")
print(token)
# 👉 eyJhbGciOiJIUzI1NiIsInR5cCI6...

# 🔑 Токен с именованным ключом
admin_token = JWTManager("admin").create_access_token("admin42")
print(admin_token)
```

---

## ⚙️ Основные возможности

* ✅ Поддержка алгоритмов `HS256`, `ES256`, `RS256`, и др.
* 🔐 Хранилище ключей по именам (`default`, `admin`, `service-X`…)
* 📤 Простой интерфейс создания/декодирования JWT
* 🛠 Расширяемая архитектура для нестандартных сценариев
* ⏱ Поддержка стандартных claim'ов: `sub`, `exp`, `iat`, `aud`, и др.

---

## 🧩 Кастомная конфигурация

```python
from jwtifypy import JWTConfig

JWTConfig.init(config={
    "keys": {
        # 🔑 Симметричный ключ (HS256) — используется общий секрет
        "default": {
            "alg": "HS256",
            "secret": "secret"
        },

        # 🔐 Асимметричный ключ (RS256) — RSA, ключи читаются из файлов
        "admin": {
            "algorithm": "RS256",
            "private_key": "file:/path/to/private.pem",
            "public_key": "file:/path/to/public.pem"
        },

        # 🧬 Асимметричный ключ (ES256) — ECDSA, приватный ключ из переменной окружения
        # public_key будет автоматически сгенерирован, если установлена библиотека `cryptography`
        "service": {
            "alg": "ES256",
            "private_key": "env:PRIVATE_KEY"
        }
    },

    # ⏱ Leeway в секундах — допускаемая погрешность в проверке времени (exp, iat)
    "leeway": 1.0,

    # ⚙️ Дополнительные опции валидации (соответствуют PyJWT)
    "options": {
        "verify_sub": False  # Не проверять наличие claim "sub"
    }
})
```

---

## 🔎 Верификация токена

```python
from jwtifypy import JWTManager

token = JWTManager.create_access_token("user123")
payload = JWTManager.decode_token(token)
print(payload["sub"])  # 👉 user123
```

---

## 🗂️ Структура проекта

```
jwtifypy/
├── __init__.py          # Основной интерфейс библиотеки
├── manager.py           # Класс JWTManager
├── config.py            # Конфигурация и инициализация
├── key.py               # Обработка ключей (HS/RS/ES)
├── store.py             # Хранилище JWTKeyStore
├── exceptions.py        # Кастомные исключения
└── utils.py             # Вспомогательные утилиты
```

---

## 🧪 Тестирование

```bash
pytest tests/
```

---

## 🛡️ Рекомендации по безопасности

* ❗ **Не храните секреты в коде.** Используйте переменные окружения.
* 🔐 Используйте `RS256`/`ES256` для межсервисной авторизации.
* ⏳ Устанавливайте короткое время жизни токенов (`exp`).
* 🔎 Включайте и проверяйте claims, если безопасность важна (`iss`, `aud`, `sub`).

---

## 📜 Лицензия

MIT © 2025
Created by \[LordCode Projects] / \[Dybfuo Projects]

