s-authkit-server 0.1.1__py3-none-any.whl

authkit_server/__init__.py

@@ -0,0 +1,68 @@
+"""s-authkit-server — СЕРВЕРНОЕ ядро авторизации для Skillery проектов.
+
+Сторона сервера: наш бэкенд авторизует СВОИХ пользователей — выпускает и проверяет
+собственные токены, хранит и ротирует refresh, хеширует пароли. Зеркальный кит
+``s-authkit-client`` (импорт ``authkit_client``) решает обратную задачу — доступ
+НАШЕГО кода к ЧУЖИМ сервисам (сессии, секреты, OAuth-обновление, живая проба).
+Суффикс в имени и есть указатель стороны: ``_server`` против ``_client``.
+
+Чистая инфраструктура без завязок на конкретное приложение: 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_server.exceptions import (
+    AuthKitError,
+    PasswordHashError,
+    RefreshTokenError,
+    TokenError,
+)
+from authkit_server.password import (
+    Argon2PasswordHasher,
+    IPasswordHasher,
+    PasswordHasher,
+)
+from authkit_server.refresh import IRefreshTokenStore, RefreshTokenRecord
+from authkit_server.token import (
+    ITokenIssuer,
+    JoseTokenIssuer,
+    TokenClaims,
+    TokenIssuer,
+    TokenIssueRequest,
+    TokenPair,
+    ensure_jwt_keypair,
+)
+
+__all__ = [
+    # exceptions
+    "AuthKitError",
+    "TokenError",
+    "RefreshTokenError",
+    "PasswordHashError",
+    # token
+    "TokenPair",
+    "TokenClaims",
+    "TokenIssueRequest",
+    "ITokenIssuer",
+    "TokenIssuer",
+    "JoseTokenIssuer",
+    "ensure_jwt_keypair",
+    # refresh
+    "RefreshTokenRecord",
+    "IRefreshTokenStore",
+    # password
+    "IPasswordHasher",
+    "PasswordHasher",
+    "Argon2PasswordHasher",
+]

authkit_server/exceptions.py

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

authkit_server/password/__init__.py

@@ -0,0 +1,10 @@
+"""Password hashing."""
+from __future__ import annotations
+
+from authkit_server.password.hasher import (
+    Argon2PasswordHasher,
+    IPasswordHasher,
+    PasswordHasher,
+)
+
+__all__ = ["IPasswordHasher", "PasswordHasher", "Argon2PasswordHasher"]

authkit_server/password/hasher.py

@@ -0,0 +1,85 @@
+"""Password hasher через passlib (алгоритм по умолчанию — Argon2id)."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from passlib.context import CryptContext
+
+from authkit_server.exceptions import PasswordHashError
+
+
+@runtime_checkable
+class IPasswordHasher(Protocol):
+    """Ролевой контракт хешера паролей (structural typing).
+
+    Развязывает потребителя от конкретного алгоритма: код зависит от роли
+    (hash/verify), а не от Argon2/bcrypt/etc. Помечен ``@runtime_checkable`` —
+    доступна проверка ``isinstance(x, IPasswordHasher)``.
+    """
+
+    def hash(self, raw: str) -> str:
+        """Хеширует plaintext-пароль в self-contained хеш."""
+        ...
+
+    def verify(self, raw: str, hashed: str) -> bool:
+        """Проверяет plaintext-пароль против хеша."""
+        ...
+
+
+class PasswordHasher:
+    """Password hasher через passlib (Argon2id по умолчанию).
+
+    Публичное имя не завязано на алгоритм: класс реализует роль
+    ``IPasswordHasher``, а конкретная схема (Argon2id) — деталь реализации.
+    Использует passlib с настройками для интерактивных 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
+
+
+# Deprecated-алиас: публичное имя развязано с алгоритмом (Argon2PasswordHasher →
+# PasswordHasher). Старое имя остаётся импортируемым для обратной совместимости.
+Argon2PasswordHasher = PasswordHasher
+
+# Статическая проверка: PasswordHasher структурно удовлетворяет IPasswordHasher.
+_conforms_to_protocol: type[IPasswordHasher] = PasswordHasher
+
+
+__all__ = ["IPasswordHasher", "PasswordHasher", "Argon2PasswordHasher"]

authkit_server/refresh/__init__.py

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

authkit_server/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_server/token/__init__.py

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

authkit_server/token/jose_issuer.py

@@ -0,0 +1,317 @@
+"""JWT RS256 issuer + persistent refresh-tokens через IRefreshTokenStore."""
+from __future__ import annotations
+
+import secrets
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Protocol, runtime_checkable
+
+from jose import jwt
+
+from authkit_server.exceptions import RefreshTokenError, TokenError
+from authkit_server.refresh.models import IRefreshTokenStore, RefreshTokenRecord
+from authkit_server.token.models import TokenClaims, TokenIssueRequest, TokenPair
+
+
+@runtime_checkable
+class ITokenIssuer(Protocol):
+    """Ролевой контракт издателя токенов (structural typing).
+
+    Позволяет типизировать потребителей против абстракции, а не против
+    конкретной реализации ``TokenIssuer``. Помечен ``@runtime_checkable``,
+    поэтому доступна проверка ``isinstance(x, ITokenIssuer)`` по наличию
+    методов издателя: issue (выпуск пары) / verify (верификация access).
+    """
+
+    async def issue_pair(
+        self,
+        *,
+        user_id: str,
+        permissions: set[str],
+    ) -> TokenPair:
+        """Выпускает пару токенов (access + refresh)."""
+        ...
+
+    def verify_access(self, token: str) -> TokenClaims:
+        """Верифицирует и декодирует access-токен."""
+        ...
+
+    async def rotate_refresh(self, refresh_token: str) -> TokenPair:
+        """Ротирует refresh-токен, выдавая новую пару."""
+        ...
+
+    async def revoke_all_for_user(self, user_id: str) -> int:
+        """Отзывает все refresh-токены пользователя."""
+        ...
+
+
+class TokenIssuer:
+    """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(self, request: TokenIssueRequest) -> TokenPair:
+        """Выпускает пару токенов из сгруппированного запроса.
+
+        Удобная обёртка над ``issue_pair``: принимает ``TokenIssueRequest``
+        вместо длинного списка kwargs. Эквивалентна ``issue_pair`` с теми же
+        полями.
+
+        Args:
+            request: Параметры выпуска (см. TokenIssueRequest).
+
+        Returns:
+            TokenPair с access и refresh токенами.
+        """
+        return await self.issue_pair(
+            user_id=request.user_id,
+            company_id=request.company_id,
+            role_id=request.role_id,
+            permissions=set(request.permissions),
+            role_slug=request.role_slug,
+            password_changed_at=request.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
+
+        # Подпись/issuer/срок валидны, но payload может недосчитаться обязательных
+        # claim'ов (sub/iat/exp/jti) — не роняем KeyError/TypeError наружу,
+        # а превращаем в доменную TokenError.
+        try:
+            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"),
+            )
+        except (KeyError, TypeError, ValueError, OverflowError, OSError) as e:
+            raise TokenError(f"Malformed token claims: {e}") from e
+
+    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)
+
+
+# Deprecated-алиас: публичное имя класса переименовано JoseTokenIssuer → TokenIssuer
+# (модуль jose_issuer остаётся внутренним). Старое имя остаётся импортируемым для
+# обратной совместимости — используйте TokenIssuer в новом коде.
+JoseTokenIssuer = TokenIssuer
+
+# Статическая проверка: TokenIssuer структурно удовлетворяет контракту ITokenIssuer.
+_conforms_to_protocol: type[ITokenIssuer] = TokenIssuer
+
+
+__all__ = ["ITokenIssuer", "TokenIssuer", "JoseTokenIssuer"]

authkit_server/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_server/token/models.py

@@ -0,0 +1,99 @@
+"""Value objects для токенов: TokenPair, TokenClaims, TokenIssueRequest."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class TokenIssueRequest:
+    """Параметры выпуска пары токенов, сгруппированные в один объект.
+
+    Заменяет длинный список именованных аргументов ``issue_pair`` одним
+    value-объектом: удобнее передавать, расширять и тестировать. Обязателен
+    только ``user_id``; остальное — опциональный контекст авторизации.
+    """
+
+    user_id: str
+    """Идентификатор пользователя."""
+
+    permissions: frozenset[str] = field(default_factory=frozenset)
+    """Набор прав (snapshot для backward-compat; пуст по умолчанию)."""
+
+    company_id: str | None = None
+    """Идентификатор активной компании (или None)."""
+
+    role_id: str | None = None
+    """Идентификатор роли (не кладётся в JWT; для audit в refresh-записи)."""
+
+    role_slug: str | None = None
+    """Slug роли (если есть — кладётся в токен для резолва прав из БД)."""
+
+    password_changed_at: datetime | None = None
+    """Момент последней смены пароля (informational claim)."""
+
+
+@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", "TokenIssueRequest"]

s_authkit_server-0.1.1.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: s-authkit-server
+Version: 0.1.1
+Summary: Серверная авторизация своих пользователей: JWT RS256 + refresh-tokens + Argon2 hashing. Пара к s-authkit-client (доступ к чужим сервисам). 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-server
+
+СЕРВЕРНОЕ ядро авторизации для Skillery проектов: JWT RS256, refresh-token management,
+Argon2 hashing. Импорт — `authkit_server`.
+
+**Версия:** 0.1.1  
+**Лицензия:** MIT  
+**Зависимости:** `python-jose[cryptography]`, `passlib[argon2]`, `cryptography`
+
+## Какая это сторона
+
+| Кит | Импорт | Чью авторизацию решает |
+| --- | --- | --- |
+| `s-authkit-server` (этот) | `authkit_server` | НАШ сервис авторизует СВОИХ пользователей: свои токены, свои пароли, свои refresh |
+| `s-authkit-client` | `authkit_client` | НАШ код получает доступ к ЧУЖИМ сервисам: сессии, секреты, OAuth-обновление, живая проба |
+
+Суффикс имени и есть указатель стороны. До 0.1.1 этот кит назывался `s-authkit`
+(импорт `authkit`) — из-за пары «`authkit` / `authkit-client`» серверный кит читался
+как SDK к клиентскому. См. раздел «Переименование» ниже.
+
+## Что входит
+
+### 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_server 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_server 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_server 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_server/
+├── __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_server import ...` вместо локального кода
+2. Обёрнет `RefreshTokenRecord` в ORM-адаптер для своей БД
+3. Оставит PermissionResolver/OAuth/ExchangeCode локально
+
+## Переименование (0.1.0 → 0.1.1)
+
+Кит переименован: дистрибутив `s-authkit` → `s-authkit-server`, импорт `authkit` →
+`authkit_server`. Публичный API (имена классов и функций) не менялся — правится только
+строка импорта и строка зависимости.
+
+Со старым дистрибутивом на PyPI:
+
+- `s-authkit==0.1.0` остаётся опубликованным как есть — его не отзываем (yank) и не
+  удаляем: он рабочий, а отзыв сломал бы любую уже собранную сборку;
+- **новых выпусков под именем `s-authkit` больше не будет** — имя заморожено на 0.1.0;
+- переименование на PyPI «на месте» невозможно: `s-authkit-server` — это НОВЫЙ
+  дистрибутив, первый его выпуск — 0.1.1 (нумерация продолжает историю кита, а не
+  начинается заново, чтобы версия читалась как «то же ядро, новое имя»).
+
+Миграция потребителя — две строки:
+
+```diff
+-"s-authkit>=0.1.0",
++"s-authkit-server>=0.1.1",
+```
+
+```diff
+-from authkit import Argon2PasswordHasher, ensure_jwt_keypair
++from authkit_server import Argon2PasswordHasher, ensure_jwt_keypair
+```
+
+## Лицензия
+
+MIT

s_authkit_server-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+authkit_server/__init__.py,sha256=6AiNtjSY9JOGmY6vb3VD_HerS2gNoTkjTgO7tKYkRJE,2419
+authkit_server/exceptions.py,sha256=dfXKyAWAOwe2mBLdjdN_fUpY4ayrxyNLAHsRjAjdmMg,662
+authkit_server/password/__init__.py,sha256=uCHRUoo4nmyoCdqT-oRTU7GsBpj-7mR5WW7N_2yk4J8,247
+authkit_server/password/hasher.py,sha256=EQlSH1hkEZtgXZz4apU8DAVe9rm2hkkLd7cvzKYFdGY,3481
+authkit_server/refresh/__init__.py,sha256=bbPK7zcTLpX8LmVSPpQRRL3CZvZMlcfu6OumDR0Z5rA,235
+authkit_server/refresh/models.py,sha256=_Uyohqs3d0AAG5eFGG0VS7K_ScfVl-sQrJZHM-fD2Rg,8826
+authkit_server/token/__init__.py,sha256=p25ucap6qG0EwCYKNxmgiIR2zfqfWcugkseZmCqKhBU,494
+authkit_server/token/jose_issuer.py,sha256=fKTPXC4I_hjoEb_Gfaj8N7rbTldr4VlU2ZwlxAfSFtU,13120
+authkit_server/token/keys.py,sha256=hkFB2lx28aOQZg86nj-FwU8Xtsc9-BA9RmMbKMVap44,1840
+authkit_server/token/models.py,sha256=EFzuoWWqqEl3wOtrL4nHnACwkwkEuCBSe8JARnxcqgo,3966
+s_authkit_server-0.1.1.dist-info/METADATA,sha256=F_8fxzi_EMsOcsv28opj5ZbwHWYkdoovlJQ_Dxb3iug,8907
+s_authkit_server-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+s_authkit_server-0.1.1.dist-info/licenses/LICENSE,sha256=j9GKJmUNdQuKRUbKhbpv0uyMaL99xsxE6L2TDtXuaZ4,1063
+s_authkit_server-0.1.1.dist-info/RECORD,,

s_authkit_server-0.1.1.dist-info/WHEEL

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

s_authkit_server-0.1.1.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.