s-authkit 0.1.0__tar.gz

s_authkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Все значительные изменения этого проекта будут документироваться в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+и этот проект соответствует [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-02
+
+### Added
+
+- **JWT RS256 issuer** (`JoseTokenIssuer`): выпуск и верификация JWT access-токенов с асимметричным ключом
+- **Persistent refresh-tokens** (`RefreshTokenRecord`, `IRefreshTokenStore`): хранение и ротация refresh-токенов с хешированием SHA256
+- **Argon2 password hashing** (`Argon2PasswordHasher`): хеширование паролей через passlib с Argon2id
+- **RSA keypair generation** (`ensure_jwt_keypair`): утилита для создания RSA 2048 ключей в PEM-формате
+- **Comprehensive test suite**: 38 unit и integration тестов с coverage ≥80%
+- **Protocol-based architecture**: `IRefreshTokenStore` как Protocol для контрактного дизайна
+
+### Notes
+
+- Первый релиз модуля `s-authkit` как отделённого ядра авторизации для Skillery проектов
+- Нет завязок на конкретное приложение: только чистая инфраструктура
+- OAuth, PermissionResolver, ExchangeCode отложены на v0.2+
+- Все методы асинхронные (async/await)
+- Python ≥3.11, зависимости: python-jose[cryptography], passlib[argon2], cryptography

s_authkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_authkit-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: s-authkit
+Version: 0.1.0
+Summary: JWT RS256 + refresh-tokens + Argon2 hashing — чистая инфраструктура авторизации для Skillery проектов. 0 завязок на конкретное приложение.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: passlib[argon2]>=1.7.4
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# s-authkit
+
+Ядро авторизации для Skillery проектов: JWT RS256, refresh-token management, Argon2 hashing.
+
+**Версия:** 0.1 (первый релиз)  
+**Лицензия:** MIT  
+**Зависимости:** `python-jose[cryptography]`, `passlib[argon2]`, `cryptography`
+
+## Что входит
+
+### JWT access-токены (RS256)
+- `JoseTokenIssuer` — выпуск и верификация JWT
+- `TokenPair` / `TokenClaims` — value objects для типизации
+- `ensure_jwt_keypair` — генерация RSA 2048 ключей
+
+### Persistent refresh-tokens
+- `IRefreshTokenStore` — protocol для БД-реализации
+- `RefreshTokenRecord` — агрегат с хешированием и валидацией
+- Rotation с audit-trail (`rotated_from`)
+
+### Password hashing
+- `Argon2PasswordHasher` — Argon2id через passlib
+
+## Примеры
+
+### 1. Инициализация
+
+```python
+from pathlib import Path
+from authkit import (
+    JoseTokenIssuer,
+    Argon2PasswordHasher,
+    ensure_jwt_keypair,
+)
+
+# Создаём ключи (если нет)
+keys_dir = Path.home() / ".myapp" / "keys"
+ensure_jwt_keypair(
+    private_path=keys_dir / "jwt_private.pem",
+    public_path=keys_dir / "jwt_public.pem",
+)
+
+# Прочитаем ключи
+private_key = (keys_dir / "jwt_private.pem").read_text()
+public_key = (keys_dir / "jwt_public.pem").read_text()
+
+# Создаём компоненты
+hasher = Argon2PasswordHasher()
+issuer = JoseTokenIssuer(
+    private_key_pem=private_key,
+    public_key_pem=public_key,
+    issuer="myproject.com",
+    access_ttl_min=15,
+    refresh_ttl_days=30,
+    refresh_store=your_store_impl,  # реализуете вы
+)
+```
+
+### 2. Login (выпуск пары токенов)
+
+```python
+async def login_with_password(username: str, password: str):
+    # Получаем юзера из БД
+    user = await db.get_user_by_username(username)
+    if not user:
+        raise ValueError("User not found")
+    
+    # Проверяем пароль
+    if not hasher.verify(password, user.password_hash):
+        raise ValueError("Invalid password")
+    
+    # Выпускаем пару
+    pair = await issuer.issue_pair(
+        user_id=str(user.id),
+        company_id=str(user.active_company_id) if user.active_company_id else None,
+        permissions={"skill.read", "skill.install"},
+    )
+    return pair
+```
+
+### 3. Middleware (верификация токена)
+
+```python
+from authkit import TokenError
+
+async def auth_middleware(request, call_next):
+    auth_header = request.headers.get("Authorization", "")
+    if not auth_header.startswith("Bearer "):
+        return Response("Unauthorized", status_code=401)
+    
+    token = auth_header[7:]
+    try:
+        claims = issuer.verify_access(token)
+    except TokenError as e:
+        return Response(f"Invalid token: {e}", status_code=401)
+    
+    request.state.claims = claims
+    return await call_next(request)
+```
+
+### 4. Refresh (rotation)
+
+```python
+async def refresh_session(refresh_token: str):
+    try:
+        new_pair = await issuer.rotate_refresh(refresh_token)
+    except RefreshTokenError as e:
+        raise Unauthorized(f"Refresh failed: {e}")
+    return new_pair
+```
+
+### 5. Реализация IRefreshTokenStore
+
+```python
+from authkit import RefreshTokenRecord, IRefreshTokenStore
+
+class PostgresRefreshTokenStore:
+    def __init__(self, db_engine):
+        self.engine = db_engine
+    
+    async def save(self, record: RefreshTokenRecord) -> None:
+        # INSERT/UPDATE в БД
+        async with self.engine.begin() as conn:
+            await conn.execute(
+                "INSERT INTO refresh_tokens (user_id, token_hash, ...) VALUES (...)"
+            )
+    
+    async def get_by_hash(self, token_hash: str) -> RefreshTokenRecord | None:
+        # SELECT * FROM refresh_tokens WHERE token_hash = ?
+        ...
+    
+    async def revoke_all_for_user(self, user_id: str) -> int:
+        # UPDATE refresh_tokens SET revoked_at = NOW() WHERE user_id = ?
+        ...
+    
+    # Реализуете остальные методы Protocol'а
+```
+
+## Архитектура
+
+```
+authkit/
+├── __init__.py              # Public API
+├── exceptions.py            # AuthKitError, TokenError, ...
+├── token/
+│   ├── models.py            # TokenPair, TokenClaims
+│   ├── jose_issuer.py       # JoseTokenIssuer
+│   └── keys.py              # ensure_jwt_keypair
+├── refresh/
+│   └── models.py            # RefreshTokenRecord, IRefreshTokenStore
+└── password/
+    └── hasher.py            # Argon2PasswordHasher
+```
+
+## Тестирование
+
+```bash
+pytest tests/                      # Все тесты
+pytest tests/ -v --cov           # С coverage report
+pytest tests/ -k "test_verify"   # Конкретный тест
+```
+
+Coverage gate: ≥ 80%.
+
+## Что НЕ входит (v0.1)
+
+- **OAuth** (YandexOAuth, ExchangeCode) — в v0.2+
+- **PermissionResolver** — остаются на стороне приложения
+- **Redis cache invalidation** — в v0.2+ как optional
+- **Signing PK/SK rotation** — будущая фича
+- **Sync обёртки** — только async API в v0.1
+
+## Интеграция в существующее приложение
+
+Типовой путь перевода существующего приложения на модуль:
+1. Импортирует `from authkit import ...` вместо локального кода
+2. Обёрнет `RefreshTokenRecord` в ORM-адаптер для своей БД
+3. Оставит PermissionResolver/OAuth/ExchangeCode локально
+
+## Лицензия
+
+MIT

s_authkit-0.1.0/README.md

@@ -0,0 +1,182 @@
+# s-authkit
+
+Ядро авторизации для Skillery проектов: JWT RS256, refresh-token management, Argon2 hashing.
+
+**Версия:** 0.1 (первый релиз)  
+**Лицензия:** MIT  
+**Зависимости:** `python-jose[cryptography]`, `passlib[argon2]`, `cryptography`
+
+## Что входит
+
+### JWT access-токены (RS256)
+- `JoseTokenIssuer` — выпуск и верификация JWT
+- `TokenPair` / `TokenClaims` — value objects для типизации
+- `ensure_jwt_keypair` — генерация RSA 2048 ключей
+
+### Persistent refresh-tokens
+- `IRefreshTokenStore` — protocol для БД-реализации
+- `RefreshTokenRecord` — агрегат с хешированием и валидацией
+- Rotation с audit-trail (`rotated_from`)
+
+### Password hashing
+- `Argon2PasswordHasher` — Argon2id через passlib
+
+## Примеры
+
+### 1. Инициализация
+
+```python
+from pathlib import Path
+from authkit import (
+    JoseTokenIssuer,
+    Argon2PasswordHasher,
+    ensure_jwt_keypair,
+)
+
+# Создаём ключи (если нет)
+keys_dir = Path.home() / ".myapp" / "keys"
+ensure_jwt_keypair(
+    private_path=keys_dir / "jwt_private.pem",
+    public_path=keys_dir / "jwt_public.pem",
+)
+
+# Прочитаем ключи
+private_key = (keys_dir / "jwt_private.pem").read_text()
+public_key = (keys_dir / "jwt_public.pem").read_text()
+
+# Создаём компоненты
+hasher = Argon2PasswordHasher()
+issuer = JoseTokenIssuer(
+    private_key_pem=private_key,
+    public_key_pem=public_key,
+    issuer="myproject.com",
+    access_ttl_min=15,
+    refresh_ttl_days=30,
+    refresh_store=your_store_impl,  # реализуете вы
+)
+```
+
+### 2. Login (выпуск пары токенов)
+
+```python
+async def login_with_password(username: str, password: str):
+    # Получаем юзера из БД
+    user = await db.get_user_by_username(username)
+    if not user:
+        raise ValueError("User not found")
+    
+    # Проверяем пароль
+    if not hasher.verify(password, user.password_hash):
+        raise ValueError("Invalid password")
+    
+    # Выпускаем пару
+    pair = await issuer.issue_pair(
+        user_id=str(user.id),
+        company_id=str(user.active_company_id) if user.active_company_id else None,
+        permissions={"skill.read", "skill.install"},
+    )
+    return pair
+```
+
+### 3. Middleware (верификация токена)
+
+```python
+from authkit import TokenError
+
+async def auth_middleware(request, call_next):
+    auth_header = request.headers.get("Authorization", "")
+    if not auth_header.startswith("Bearer "):
+        return Response("Unauthorized", status_code=401)
+    
+    token = auth_header[7:]
+    try:
+        claims = issuer.verify_access(token)
+    except TokenError as e:
+        return Response(f"Invalid token: {e}", status_code=401)
+    
+    request.state.claims = claims
+    return await call_next(request)
+```
+
+### 4. Refresh (rotation)
+
+```python
+async def refresh_session(refresh_token: str):
+    try:
+        new_pair = await issuer.rotate_refresh(refresh_token)
+    except RefreshTokenError as e:
+        raise Unauthorized(f"Refresh failed: {e}")
+    return new_pair
+```
+
+### 5. Реализация IRefreshTokenStore
+
+```python
+from authkit import RefreshTokenRecord, IRefreshTokenStore
+
+class PostgresRefreshTokenStore:
+    def __init__(self, db_engine):
+        self.engine = db_engine
+    
+    async def save(self, record: RefreshTokenRecord) -> None:
+        # INSERT/UPDATE в БД
+        async with self.engine.begin() as conn:
+            await conn.execute(
+                "INSERT INTO refresh_tokens (user_id, token_hash, ...) VALUES (...)"
+            )
+    
+    async def get_by_hash(self, token_hash: str) -> RefreshTokenRecord | None:
+        # SELECT * FROM refresh_tokens WHERE token_hash = ?
+        ...
+    
+    async def revoke_all_for_user(self, user_id: str) -> int:
+        # UPDATE refresh_tokens SET revoked_at = NOW() WHERE user_id = ?
+        ...
+    
+    # Реализуете остальные методы Protocol'а
+```
+
+## Архитектура
+
+```
+authkit/
+├── __init__.py              # Public API
+├── exceptions.py            # AuthKitError, TokenError, ...
+├── token/
+│   ├── models.py            # TokenPair, TokenClaims
+│   ├── jose_issuer.py       # JoseTokenIssuer
+│   └── keys.py              # ensure_jwt_keypair
+├── refresh/
+│   └── models.py            # RefreshTokenRecord, IRefreshTokenStore
+└── password/
+    └── hasher.py            # Argon2PasswordHasher
+```
+
+## Тестирование
+
+```bash
+pytest tests/                      # Все тесты
+pytest tests/ -v --cov           # С coverage report
+pytest tests/ -k "test_verify"   # Конкретный тест
+```
+
+Coverage gate: ≥ 80%.
+
+## Что НЕ входит (v0.1)
+
+- **OAuth** (YandexOAuth, ExchangeCode) — в v0.2+
+- **PermissionResolver** — остаются на стороне приложения
+- **Redis cache invalidation** — в v0.2+ как optional
+- **Signing PK/SK rotation** — будущая фича
+- **Sync обёртки** — только async API в v0.1
+
+## Интеграция в существующее приложение
+
+Типовой путь перевода существующего приложения на модуль:
+1. Импортирует `from authkit import ...` вместо локального кода
+2. Обёрнет `RefreshTokenRecord` в ORM-адаптер для своей БД
+3. Оставит PermissionResolver/OAuth/ExchangeCode локально
+
+## Лицензия
+
+MIT

s_authkit-0.1.0/authkit/__init__.py

@@ -0,0 +1,45 @@
+"""s-authkit — JWT ядро авторизации для Skillery проектов.
+
+Чистая инфраструктура без завязок на конкретное приложение: JWT RS256 issuing/verification,
+refresh-token management, password hashing. Переиспользуется в будущих
+микросервисах и интеграциях.
+
+**Ядро (v0.1):**
+- JWT RS256 issuer/verifier (JoseTokenIssuer)
+- Persistent refresh-token store (IRefreshTokenStore + RefreshTokenRecord)
+- Argon2 password hasher (Argon2PasswordHasher)
+- RSA keypair generation (ensure_jwt_keypair)
+
+**Отложено (v0.2+):** OAuth, PermissionResolver, ExchangeCode (app-specific).
+
+Зависимости: python-jose[cryptography], passlib[argon2], cryptography.
+"""
+from __future__ import annotations
+
+from authkit.exceptions import (
+    AuthKitError,
+    PasswordHashError,
+    RefreshTokenError,
+    TokenError,
+)
+from authkit.password import Argon2PasswordHasher
+from authkit.refresh import IRefreshTokenStore, RefreshTokenRecord
+from authkit.token import JoseTokenIssuer, TokenClaims, TokenPair, ensure_jwt_keypair
+
+__all__ = [
+    # exceptions
+    "AuthKitError",
+    "TokenError",
+    "RefreshTokenError",
+    "PasswordHashError",
+    # token
+    "TokenPair",
+    "TokenClaims",
+    "JoseTokenIssuer",
+    "ensure_jwt_keypair",
+    # refresh
+    "RefreshTokenRecord",
+    "IRefreshTokenStore",
+    # password
+    "Argon2PasswordHasher",
+]

s_authkit-0.1.0/authkit/exceptions.py

@@ -0,0 +1,34 @@
+"""Исключения модуля authkit."""
+from __future__ import annotations
+
+
+class AuthKitError(Exception):
+    """Базовое исключение модуля authkit."""
+
+    pass
+
+
+class TokenError(AuthKitError):
+    """Ошибка в работе с JWT."""
+
+    pass
+
+
+class RefreshTokenError(AuthKitError):
+    """Ошибка refresh-токена (истёк, отозван, неизвестен)."""
+
+    pass
+
+
+class PasswordHashError(AuthKitError):
+    """Ошибка хеширования пароля."""
+
+    pass
+
+
+__all__ = [
+    "AuthKitError",
+    "TokenError",
+    "RefreshTokenError",
+    "PasswordHashError",
+]

s_authkit-0.1.0/authkit/password/__init__.py

@@ -0,0 +1,6 @@
+"""Password hashing."""
+from __future__ import annotations
+
+from authkit.password.hasher import Argon2PasswordHasher
+
+__all__ = ["Argon2PasswordHasher"]

s_authkit-0.1.0/authkit/password/hasher.py

@@ -0,0 +1,55 @@
+"""Argon2 password hasher через passlib."""
+from __future__ import annotations
+
+from passlib.context import CryptContext
+
+from authkit.exceptions import PasswordHashError
+
+
+class Argon2PasswordHasher:
+    """Argon2id password hasher через passlib.
+
+    Использует passlib с Argon2id схемой, настроенной для интерактивных flow'ов
+    (~50-100ms на современном CPU). Возвращает self-contained хеши с salt,
+    верификация не требует отдельного хранения salt.
+    """
+
+    def __init__(self) -> None:
+        """Инициализирует hasher с Argon2id (passlib defaults)."""
+        self._ctx = CryptContext(schemes=["argon2"], deprecated="auto")
+
+    def hash(self, raw: str) -> str:
+        """Хеширует пароль.
+
+        Args:
+            raw: Plaintext пароль.
+
+        Returns:
+            Self-contained хеш (algorithm + salt + hash).
+
+        Raises:
+            PasswordHashError: Если хеширование не удалось.
+        """
+        try:
+            return str(self._ctx.hash(raw))
+        except Exception as e:
+            raise PasswordHashError(f"Failed to hash password: {e}") from e
+
+    def verify(self, raw: str, hashed: str) -> bool:
+        """Проверяет пароль против хеша.
+
+        Args:
+            raw: Plaintext пароль для проверки.
+            hashed: Self-contained хеш для сравнения.
+
+        Returns:
+            True если пароль совпадает, False иначе.
+        """
+        try:
+            return bool(self._ctx.verify(raw, hashed))
+        except Exception:
+            # Любая ошибка (невалидный хеш, невалидный пароль) → False
+            return False
+
+
+__all__ = ["Argon2PasswordHasher"]

s_authkit-0.1.0/authkit/refresh/__init__.py

@@ -0,0 +1,9 @@
+"""Refresh token management and store contract."""
+from __future__ import annotations
+
+from authkit.refresh.models import IRefreshTokenStore, RefreshTokenRecord
+
+__all__ = [
+    "RefreshTokenRecord",
+    "IRefreshTokenStore",
+]