s-authkit 0.1.0__py3-none-any.whl

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",
+]

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",
+]

authkit/password/__init__.py

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

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"]

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",
+]

authkit/refresh/models.py

@@ -0,0 +1,249 @@
+"""RefreshTokenRecord и IRefreshTokenStore protocol."""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Protocol
+
+
+@dataclass
+class RefreshTokenRecord:
+    """Запись о выданном refresh-токене.
+
+    В БД хранится только sha256(token_plaintext), сам токен остаётся у клиента.
+    revoked_at != None означает, что токен был отозван (обычно после rotation).
+    """
+
+    user_id: str
+    """Идентификатор пользователя."""
+
+    company_id: str | None
+    """Идентификатор активной компании на момент выдачи."""
+
+    role_id: str | None
+    """Идентификатор роли на момент выдачи."""
+
+    permissions: tuple[str, ...]
+    """Снимок прав на момент выдачи (для snapshot-based авторизации)."""
+
+    token_hash: str
+    """SHA256 хеш plaintext-токена."""
+
+    expires_at: datetime
+    """Момент истечения токена (UTC)."""
+
+    id: str | None = None
+    """Первичный ключ записи в store (назначает store при сохранении)."""
+
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    """Момент создания записи (UTC)."""
+
+    revoked_at: datetime | None = None
+    """Момент отзыва токена (None если активен)."""
+
+    rotated_from: str | None = None
+    """ID предыдущего refresh-токена (для rotation chain и audit)."""
+
+    user_agent: str | None = None
+    """User-Agent строка браузера (если есть)."""
+
+    ip_address: str | None = None
+    """IP-адрес, с которого вышёл пользователь (если есть)."""
+
+    role_slug: str | None = None
+    """Slug роли на момент выдачи (для resurrection при rotation)."""
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        user_id: str,
+        company_id: str | None,
+        role_id: str | None,
+        permissions: set[str],
+        token_hash: str,
+        expires_at: datetime,
+        rotated_from: str | None = None,
+        user_agent: str | None = None,
+        ip_address: str | None = None,
+        role_slug: str | None = None,
+    ) -> RefreshTokenRecord:
+        """Factory-метод для создания RefreshTokenRecord.
+
+        Args:
+            user_id: Идентификатор пользователя.
+            company_id: Идентификатор компании (или None).
+            role_id: Идентификатор роли (или None).
+            permissions: Набор прав (конвертится в sorted tuple).
+            token_hash: SHA256(plaintext_token).
+            expires_at: Момент истечения.
+            rotated_from: ID предыдущего токена при rotation.
+            user_agent: User-Agent (опционально).
+            ip_address: IP-адрес (опционально).
+            role_slug: Slug роли (опционально).
+
+        Returns:
+            RefreshTokenRecord с id=None (назначит store).
+        """
+        return cls(
+            user_id=user_id,
+            company_id=company_id,
+            role_id=role_id,
+            permissions=tuple(sorted(permissions)),
+            token_hash=token_hash,
+            expires_at=expires_at,
+            rotated_from=rotated_from,
+            user_agent=user_agent,
+            ip_address=ip_address,
+            role_slug=role_slug,
+        )
+
+    @staticmethod
+    def hash_token(plaintext: str) -> str:
+        """Хеширует plaintext-токен в SHA256 для хранения.
+
+        Args:
+            plaintext: Opaque refresh-токен.
+
+        Returns:
+            Hex-string SHA256 хеша.
+        """
+        return hashlib.sha256(plaintext.encode("utf-8")).hexdigest()
+
+    def is_expired(self, *, now: datetime | None = None) -> bool:
+        """Проверяет, истёк ли токен.
+
+        Args:
+            now: Момент проверки (default: UTC now).
+
+        Returns:
+            True если токен истёк.
+        """
+        check_time = now or datetime.now(UTC)
+        return check_time >= self.expires_at
+
+    def is_revoked(self) -> bool:
+        """Проверяет, отозван ли токен.
+
+        Returns:
+            True если revoked_at != None.
+        """
+        return self.revoked_at is not None
+
+    def revoke(self, *, now: datetime | None = None) -> None:
+        """Отзывает токен (устанавливает revoked_at).
+
+        Args:
+            now: Момент отзыва (default: UTC now).
+
+        Raises:
+            ValueError: Если токен уже отозван.
+        """
+        if self.revoked_at is not None:
+            raise ValueError("Refresh token already revoked")
+        self.revoked_at = now or datetime.now(UTC)
+
+
+class IRefreshTokenStore(Protocol):
+    """Контракт для хранилища refresh-токенов.
+
+    Реализует асинхронное сохранение, получение и управление refresh-токенами.
+    Потребитель (ваше приложение) реализует этот Protocol
+    для своей БД.
+    """
+
+    async def save(self, record: RefreshTokenRecord) -> None:
+        """Сохраняет новую запись refresh-токена или обновляет существующую.
+
+        Args:
+            record: Запись для сохранения.
+        """
+        ...
+
+    async def get_by_hash(self, token_hash: str) -> RefreshTokenRecord | None:
+        """Получает запись по хешу токена.
+
+        Используется при верификации refresh-токена.
+
+        Args:
+            token_hash: SHA256(plaintext_token).
+
+        Returns:
+            RefreshTokenRecord или None если не найден.
+        """
+        ...
+
+    async def get_by_id(self, record_id: str) -> RefreshTokenRecord | None:
+        """Получает запись по id.
+
+        Args:
+            record_id: Первичный ключ записи.
+
+        Returns:
+            RefreshTokenRecord или None если не найден.
+        """
+        ...
+
+    async def list_active_for_user(self, user_id: str) -> list[RefreshTokenRecord]:
+        """Список активных (не revoked, не expired) refresh-токенов пользователя.
+
+        Args:
+            user_id: Идентификатор пользователя.
+
+        Returns:
+            Список RefreshTokenRecord.
+        """
+        ...
+
+    async def revoke(self, record_id: str, *, now: datetime | None = None) -> None:
+        """Отзывает конкретный refresh-токен.
+
+        Args:
+            record_id: ID записи для отзыва.
+            now: Момент отзыва (default: UTC now).
+        """
+        ...
+
+    async def revoke_all_for_user(
+        self, user_id: str, *, now: datetime | None = None
+    ) -> int:
+        """Отзывает все refresh-токены пользователя (логаут со всех девайсов).
+
+        Args:
+            user_id: Идентификатор пользователя.
+            now: Момент отзыва (default: UTC now).
+
+        Returns:
+            Количество отозванных токенов.
+        """
+        ...
+
+    async def revoke_all_for_user_except(
+        self, user_id: str, except_id: str, *, now: datetime | None = None
+    ) -> int:
+        """Отзывает все refresh-токены КРОМЕ одного (для ротации на текущем девайсе).
+
+        Args:
+            user_id: Идентификатор пользователя.
+            except_id: ID записи, которую НЕ трогать.
+            now: Момент отзыва (default: UTC now).
+
+        Returns:
+            Количество отозванных токенов.
+        """
+        ...
+
+    async def delete_expired(self, now: datetime) -> int:
+        """Удаляет истёкшие refresh-токены (для очистки, запускается scheduler'ом).
+
+        Args:
+            now: Момент проверки (обычно UTC now).
+
+        Returns:
+            Количество удалённых записей.
+        """
+        ...
+
+
+__all__ = ["RefreshTokenRecord", "IRefreshTokenStore"]

authkit/token/__init__.py

@@ -0,0 +1,13 @@
+"""JWT token management: issuing, verification, key generation."""
+from __future__ import annotations
+
+from authkit.token.jose_issuer import JoseTokenIssuer
+from authkit.token.keys import ensure_jwt_keypair
+from authkit.token.models import TokenClaims, TokenPair
+
+__all__ = [
+    "TokenPair",
+    "TokenClaims",
+    "JoseTokenIssuer",
+    "ensure_jwt_keypair",
+]

authkit/token/jose_issuer.py

@@ -0,0 +1,247 @@
+"""JWT RS256 issuer + persistent refresh-tokens через IRefreshTokenStore."""
+from __future__ import annotations
+
+import secrets
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from jose import jwt
+
+from authkit.exceptions import RefreshTokenError, TokenError
+from authkit.refresh.models import IRefreshTokenStore, RefreshTokenRecord
+from authkit.token.models import TokenClaims, TokenPair
+
+
+class JoseTokenIssuer:
+    """JWT RS256 access-токены + persistent opaque refresh-токены.
+
+    Access-токен — короткоживущий JWT, не требует БД для верификации.
+    Refresh-токен — opaque urlsafe-строка, хранится как хеш в IRefreshTokenStore.
+    На rotation старый токен помечается revoked, выдаётся новый
+    (rotated_from = old.id для audit-trail).
+    """
+
+    def __init__(
+        self,
+        *,
+        private_key_pem: str,
+        public_key_pem: str,
+        issuer: str,
+        access_ttl_min: int,
+        refresh_ttl_days: int,
+        refresh_store: IRefreshTokenStore,
+    ) -> None:
+        """Инициализирует issuer.
+
+        Args:
+            private_key_pem: Приватный RSA ключ в PEM-формате.
+            public_key_pem: Публичный RSA ключ в PEM-формате.
+            issuer: Строка issuer'а для JWT (напр. "skillery.ru").
+            access_ttl_min: TTL access-токена в минутах.
+            refresh_ttl_days: TTL refresh-токена в днях.
+            refresh_store: Реализация IRefreshTokenStore для хранения refresh-токенов.
+        """
+        self._priv = private_key_pem
+        self._pub = public_key_pem
+        self._issuer = issuer
+        self._access_ttl = timedelta(minutes=access_ttl_min)
+        self._refresh_ttl = timedelta(days=refresh_ttl_days)
+        self._store = refresh_store
+
+    async def issue_pair(
+        self,
+        *,
+        user_id: str,
+        company_id: str | None = None,
+        role_id: str | None = None,
+        permissions: set[str],
+        role_slug: str | None = None,
+        password_changed_at: datetime | None = None,
+    ) -> TokenPair:
+        """Выпускает пару токенов (access + refresh).
+
+        Args:
+            user_id: Идентификатор пользователя.
+            company_id: Идентификатор активной компании (опционально).
+            role_id: Идентификатор роли (опционально, не кладётся в JWT).
+            permissions: Набор прав пользователя (snapshot для backward-compat).
+            role_slug: Slug роли (если есть, кладётся в токен для резолва прав из БД).
+            password_changed_at: Момент последней смены пароля (informational claim).
+
+        Returns:
+            TokenPair с access и refresh токенами.
+        """
+        return await self._issue_internal(
+            user_id=user_id,
+            company_id=company_id,
+            role_id=role_id,
+            permissions=permissions,
+            rotated_from=None,
+            role_slug=role_slug,
+            password_changed_at=password_changed_at,
+        )
+
+    async def _issue_internal(
+        self,
+        *,
+        user_id: str,
+        company_id: str | None,
+        role_id: str | None,
+        permissions: set[str],
+        rotated_from: str | None,
+        role_slug: str | None = None,
+        password_changed_at: datetime | None = None,
+    ) -> TokenPair:
+        """Внутренняя реализация выпуска пары токенов."""
+        now = datetime.now(UTC)
+        access_exp = now + self._access_ttl
+        refresh_exp = now + self._refresh_ttl
+        jti = uuid.uuid4().hex
+
+        # Формируем payload access-токена
+        access_payload: dict[str, object] = {
+            "iss": self._issuer,
+            "sub": user_id,
+            "company_id": company_id if company_id else None,
+            # Snapshot прав кладётся только если role_slug отсутствует
+            # (backward-compat с legacy токенами, но новые токены с role_slug
+            # не кладут snapshot — права резолвятся из БД).
+            **(
+                {"permissions": sorted(permissions)}
+                if role_slug is None
+                else {}
+            ),
+            "iat": int(now.timestamp()),
+            "exp": int(access_exp.timestamp()),
+            "jti": jti,
+            # Момент смены пароля (informational; enforcement читает свежее из БД).
+            **(
+                {"pwd_changed_at": int(password_changed_at.timestamp())}
+                if password_changed_at is not None
+                else {}
+            ),
+        }
+
+        if role_slug is not None:
+            access_payload["role_slug"] = role_slug
+
+        # Кодируем JWT
+        access_token = jwt.encode(access_payload, self._priv, algorithm="RS256")
+
+        # Генерируем opaque refresh-токен
+        refresh_token = secrets.token_urlsafe(32)
+
+        # Сохраняем запись в store
+        record = RefreshTokenRecord.create(
+            user_id=user_id,
+            company_id=company_id,
+            role_id=role_id,
+            permissions=permissions,
+            token_hash=RefreshTokenRecord.hash_token(refresh_token),
+            expires_at=refresh_exp,
+            rotated_from=rotated_from,
+            role_slug=role_slug,
+        )
+        await self._store.save(record)
+
+        return TokenPair(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            access_expires_at=access_exp,
+            refresh_expires_at=refresh_exp,
+        )
+
+    def verify_access(self, token: str) -> TokenClaims:
+        """Декодирует и верифицирует JWT access-токен.
+
+        Проверяет подпись (RS256), issuer и срок действия.
+
+        Args:
+            token: JWT access-токен.
+
+        Returns:
+            TokenClaims с распарсенными claims.
+
+        Raises:
+            TokenError: Если токен невалиден, срок истёк или подпись неверна.
+        """
+        try:
+            payload = jwt.decode(
+                token,
+                self._pub,
+                algorithms=["RS256"],
+                issuer=self._issuer,
+                options={"verify_aud": False},
+            )
+        except Exception as e:
+            raise TokenError(f"Invalid token: {e}") from e
+
+        return TokenClaims(
+            user_id=payload["sub"],
+            company_id=payload.get("company_id"),
+            permissions=frozenset(payload.get("permissions", [])),
+            issued_at=datetime.fromtimestamp(payload["iat"], UTC),
+            expires_at=datetime.fromtimestamp(payload["exp"], UTC),
+            jti=payload["jti"],
+            role_slug=payload.get("role_slug"),
+        )
+
+    async def rotate_refresh(self, refresh_token: str) -> TokenPair:
+        """Проверяет refresh-токен, отзывает старый, выпускает новую пару.
+
+        Implements refresh token rotation: старый токен помечается revoked,
+        новая пара выпускается с роль, правами и метаданными из старой записи.
+
+        Args:
+            refresh_token: Opaque refresh-токен (plaintext).
+
+        Returns:
+            Новая TokenPair.
+
+        Raises:
+            RefreshTokenError: Если токен невалиден, истёк, отозван или неизвестен.
+        """
+        token_hash = RefreshTokenRecord.hash_token(refresh_token)
+        record = await self._store.get_by_hash(token_hash)
+
+        if record is None:
+            raise RefreshTokenError("Unknown refresh token")
+
+        if record.is_revoked():
+            # Переиспользование отозванного токена — security incident.
+            # Отзываем все токены юзера для безопасности.
+            await self._store.revoke_all_for_user(record.user_id)
+            raise RefreshTokenError(
+                "Refresh token already revoked; all user sessions revoked for security"
+            )
+
+        if record.is_expired():
+            raise RefreshTokenError("Refresh token expired")
+
+        # Отзываем старый токен
+        if record.id is not None:
+            await self._store.revoke(record.id)
+
+        # Выпускаем новую пару с сохранением контекста
+        return await self._issue_internal(
+            user_id=record.user_id,
+            company_id=record.company_id,
+            role_id=record.role_id,
+            permissions=set(record.permissions),
+            rotated_from=record.id,
+            role_slug=record.role_slug,
+        )
+
+    async def revoke_all_for_user(self, user_id: str) -> int:
+        """Отзывает все refresh-токены пользователя (логаут со всех девайсов).
+
+        Args:
+            user_id: Идентификатор пользователя.
+
+        Returns:
+            Количество отозванных токенов.
+        """
+        return await self._store.revoke_all_for_user(user_id)
+
+
+__all__ = ["JoseTokenIssuer"]

authkit/token/keys.py

@@ -0,0 +1,46 @@
+"""Генерация и загрузка RSA-ключей для JWT."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+
+def ensure_jwt_keypair(*, private_path: Path, public_path: Path) -> None:
+    """Создаёт RSA 2048 keypair если файлов нет.
+
+    Если файлы уже существуют, ничего не делает (идемпотентная операция).
+    Если директория не существует, создаёт её (mkdir -p).
+
+    Args:
+        private_path: Путь для сохранения приватного ключа (PEM format).
+        public_path: Путь для сохранения публичного ключа (PEM format).
+    """
+    if private_path.exists() and public_path.exists():
+        return
+
+    # Создаём директории если их нет
+    private_path.parent.mkdir(parents=True, exist_ok=True)
+    public_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Генерируем RSA 2048 keypair
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+    # Сохраняем приватный ключ (PKCS8, без шифрования)
+    private_pem = key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    private_path.write_bytes(private_pem)
+
+    # Сохраняем публичный ключ
+    public_pem = key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    public_path.write_bytes(public_pem)
+
+
+__all__ = ["ensure_jwt_keypair"]

authkit/token/models.py

@@ -0,0 +1,71 @@
+"""Value objects для токенов: TokenPair, TokenClaims."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class TokenPair:
+    """Пара access + refresh JWT токенов.
+
+    Access-токен — короткоживущий JWT RS256 (не требует БД для верификации).
+    Refresh-токен — opaque urlsafe-строка, хранится как хеш в IRefreshTokenStore.
+    """
+
+    access_token: str
+    """JWT access-токен (RS256)."""
+
+    refresh_token: str
+    """Opaque refresh-токен (urlsafe)."""
+
+    access_expires_at: datetime
+    """Момент истечения access-токена (UTC)."""
+
+    refresh_expires_at: datetime
+    """Момент истечения refresh-токена (UTC)."""
+
+
+@dataclass(frozen=True, slots=True)
+class TokenClaims:
+    """Расшифрованные claims из JWT access-токена.
+
+    Содержит идентификационные данные юзера и опциональный снимок прав
+    (для backward-compat с legacy токенами). В современных токенах права
+    резолвятся из БД по role_slug.
+    """
+
+    user_id: str
+    """Идентификатор пользователя (типизирует потребитель)."""
+
+    company_id: str | None
+    """Идентификатор активной компании (None если логин без компании)."""
+
+    permissions: frozenset[str]
+    """Снимок прав на момент выдачи токена.
+
+    Для backward-compat с legacy токенами (до E5). Современные токены
+    резолвят права из БД по role_slug, не доверяя snapshot'у.
+    """
+
+    issued_at: datetime
+    """Момент выдачи токена (UTC)."""
+
+    expires_at: datetime
+    """Момент истечения токена (UTC)."""
+
+    jti: str
+    """JWT ID — уникальный идентификатор этого токена (UUID hex).
+
+    Используется для revocation tracking по RFC 7519 §4.1.7.
+    """
+
+    role_slug: str | None = None
+    """Slug роли на момент выдачи (если есть).
+
+    Новые токены (E5+) кладут role_slug для резолва прав из БД.
+    Legacy токены (до E5) = None.
+    """
+
+
+__all__ = ["TokenPair", "TokenClaims"]

s_authkit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+authkit/__init__.py,sha256=prkSfCH0YcS_p60thT3Qq_ZSRaHevbsvXt26AwcAzUc,1517
+authkit/exceptions.py,sha256=ZqgxdRY8b_0XkfyH3K_wnqfA1maj0d1aeB1icJiamX8,648
+authkit/password/__init__.py,sha256=3euzmIIZm-AQpZ3gzTsvVLRSDdkmbb2v8dD5VzNXTYM,153
+authkit/password/hasher.py,sha256=eovF2jxgVaapyDzv0B68m866A7O6Fqvs_dpL0YHwahU,1911
+authkit/refresh/__init__.py,sha256=S7vFIN8UwRCeQHljLOnJIiG3ny1lJGDju2Sk4dISHHQ,228
+authkit/refresh/models.py,sha256=Ud-KHKKYTmco1v4pOkMKt7sK_abkCgVZFJRLaDMbB1w,9075
+authkit/token/__init__.py,sha256=cvcVH5ELdVYB4wparFfWJhJRHxzUc6u8fYF_BbZr39E,363
+authkit/token/jose_issuer.py,sha256=UfB5ZvbC7tz7m5LxOJXTlra9M9eyjZU8bs7BLhlczcI,9707
+authkit/token/keys.py,sha256=hkFB2lx28aOQZg86nj-FwU8Xtsc9-BA9RmMbKMVap44,1840
+authkit/token/models.py,sha256=cNAADu1MRdqoDnCL_wjhtJFqZBIsLo456EIwxUo7N5M,2544
+s_authkit-0.1.0.dist-info/METADATA,sha256=EPW_kdipgDq6XAuodfftCquTX00XC4RV8BhzgmKbhA4,6394
+s_authkit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+s_authkit-0.1.0.dist-info/licenses/LICENSE,sha256=j9GKJmUNdQuKRUbKhbpv0uyMaL99xsxE6L2TDtXuaZ4,1063
+s_authkit-0.1.0.dist-info/RECORD,,

s_authkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

s_authkit-0.1.0.dist-info/licenses/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.