xn-auth 0.2.55__tar.gz → 0.2.56__tar.gz

xn_auth-0.2.56/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+x-auth (`xn-auth` on PyPI) is a JWT cookie-based authentication middleware for Litestar (ASGI framework). It handles Telegram-based authentication via Mini Apps (TMA) and Login Widget (TWA), with automatic token refresh when expired.
+
+## Build & Publish
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Build package
+python -m build
+
+# Publish to PyPI
+twine upload dist/*
+```
+
+## Architecture
+
+### Authentication Flow
+
+1. **Entry point**: `Auth` class in `controller.py` - initializes `JWTCookieAuth` from Litestar with custom middleware
+2. **Endpoints**: `/auth/tma` (Mini App initData) and `/auth/twa` (Login Widget) - both validate Telegram signatures and issue JWT tokens
+3. **Token handling**: Custom `Tok` class in `middleware.py` extends `Token` to catch `ExpiredSignatureError` and re-encode with fresh timestamps
+4. **Auto-refresh**: `JWTAuthMiddleware` intercepts expired tokens, checks if user is blocked via `User.permissions()`, updates role if changed, and sets new cookie
+
+### Key Components
+
+- **`Auth`** (`controller.py`): Main class instantiated by consuming applications. Pass the Telegram bot token as `sec`, optionally a custom `User` model, excluded paths, and cookie domain.
+- **`JWTAuthMiddleware`** (`middleware.py`): Wraps Litestar's `JWTCookieAuthenticationMiddleware`. On `ExpiredSignature`, fetches user permissions from DB and issues refreshed token via `Set-Cookie` header injection.
+- **`User`** model (`models.py`): Tortoise ORM model with `tg_upsert()` for login and `permissions()` for token refresh checks. Related to `Username` for Telegram user ID mapping.
+- **Role system** (`enums.py`): Bitmask-based roles (`READER=4`, `WRITER=2`, `MANAGER=6`, `ADMIN=7`) using `RoleScope` flags.
+
+### Token Contents
+
+JWT extras stored beyond standard claims:
+- `role`: User's current role (refreshed on token renewal)
+- `blocked`: Whether user has blocked the bot (checked via `allows_write_to_pm` or `send_chat_action`)
+
+### Dependencies
+
+- `litestar` - ASGI framework (JWT auth support)
+- `tortoise-orm` via `xn-model` - Database models
+- `aiogram` - Telegram signature validation and bot API
+- `kurigram` - Pyrogram fork for session/peer models
+- `pyjwt` - JWT encoding/decoding
+- `msgspec` - Fast serialization
+
+### Excluded Paths
+
+Default paths excluded from auth: `/schema`, `/auth`, `/public`

{xn_auth-0.2.55/xn_auth.egg-info → xn_auth-0.2.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xn-auth
-Version: 0.2.55
+Version: 0.2.56
 Summary: Auth adapter for XN-Api framework
 Author-email: Artemiev <mixartemev@gmail.com>
 License: MIT
@@ -22,6 +22,10 @@ Requires-Dist: twine; extra == "dev"
 # X-Auth
 ###### JWT authentication for x-api
 
+JWT cookie based Auth Middleware for ASGI framework.
+Stores in user_id, issued and expired dates, user role and blocked state.
+When token expired, it is automatically fetching user from db, and if he is not blocked now, then updates issue/expire dates, and user role if it was changed after the last user fetch.
+
 #### Requirements
 - Python >= 3.12
 

xn_auth-0.2.56/README.md

@@ -0,0 +1,17 @@
+# X-Auth
+###### JWT authentication for x-api
+
+JWT cookie based Auth Middleware for ASGI framework.
+Stores in user_id, issued and expired dates, user role and blocked state.
+When token expired, it is automatically fetching user from db, and if he is not blocked now, then updates issue/expire dates, and user role if it was changed after the last user fetch.
+
+#### Requirements
+- Python >= 3.12
+
+### INSTALL
+```bash
+pip install xn-auth
+```
+
+---
+Made with ❤ on top of the [X-Model](https://github.com/XyncNet/x-model).

xn_auth-0.2.56/x_auth/exceptions.py

@@ -0,0 +1,5 @@
+from jwt import ExpiredSignatureError
+
+
+class ExpiredSignature(Exception):
+    def __init__(self, uid: int, encoded_token: str, secret: str, _e: ExpiredSignatureError): ...

{xn_auth-0.2.55 → xn_auth-0.2.56}/x_auth/middleware.py

@@ -38,8 +38,8 @@ class Tok(Token):
                 }
             )
             tok = convert(payload, cls, strict=False)
-            encoded_token = tok.encode(secret, algorithms[0])  # check where from getting algorithms
-            raise ExpiredSignature(int(payload["sub"]), encoded_token, e)
+            encoded_token = tok.encode(secret, algorithms[0])
+            raise ExpiredSignature(int(payload["sub"]), encoded_token, secret, e)
 
 
 class JWTAuthMiddleware(JWTCookieAuthenticationMiddleware):
@@ -47,10 +47,17 @@ class JWTAuthMiddleware(JWTCookieAuthenticationMiddleware):
         try:
             await super().__call__(scope, receive, send)
         except ExpiredSignature as e:
-            uid, uet, _e = e.args  # uid, updated encoded token
-            if await scope["app"].state.get("user_model").is_blocked(uid):
+            uid, uet, secret, _e = e.args  # uid, updated encoded token
+            blocked, role = await scope["app"].state.get("user_model").permissions(uid)
+            if blocked:
                 logging.error(f"User#{uid} can't refresh. Blocked!")
                 raise _e
+            payload = Tok.decode_payload(uet, secret, ["HS256"])
+            if role.value != payload["extras"]["role"]:
+                # update user role in jwtoken
+                payload["extras"]["role"] = role.value
+                tok = convert(payload, Tok, strict=False)
+                uet = tok.encode(secret, "HS256")
 
             async def send_wrapper(msg: Message) -> None:
                 if msg["type"] == "http.response.start":

{xn_auth-0.2.55 → xn_auth-0.2.56}/x_auth/models.py

@@ -78,8 +78,9 @@ class User(Model):
         return user_dict
 
     @classmethod
-    async def is_blocked(cls, sid: str) -> bool:
-        return (await cls[int(sid)]).blocked
+    async def permissions(cls, self_id: str) -> tuple[bool, Role]:
+        user = await cls[self_id]
+        return user.blocked, user.role
 
     @classmethod
     async def tg_upsert(cls, u: PyroUser | AioUser | WebAppUser, blocked: bool = None) -> tuple["User", bool]:

{xn_auth-0.2.55 → xn_auth-0.2.56/xn_auth.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xn-auth
-Version: 0.2.55
+Version: 0.2.56
 Summary: Auth adapter for XN-Api framework
 Author-email: Artemiev <mixartemev@gmail.com>
 License: MIT
@@ -22,6 +22,10 @@ Requires-Dist: twine; extra == "dev"
 # X-Auth
 ###### JWT authentication for x-api
 
+JWT cookie based Auth Middleware for ASGI framework.
+Stores in user_id, issued and expired dates, user role and blocked state.
+When token expired, it is automatically fetching user from db, and if he is not blocked now, then updates issue/expire dates, and user role if it was changed after the last user fetch.
+
 #### Requirements
 - Python >= 3.12
 

{xn_auth-0.2.55 → xn_auth-0.2.56}/xn_auth.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 .env.dist
 .gitignore
 .pre-commit-config.yaml
+CLAUDE.md
 README.md
 makefile
 pyproject.toml

xn_auth-0.2.55/README.md

@@ -1,13 +0,0 @@
-# X-Auth
-###### JWT authentication for x-api
-
-#### Requirements
-- Python >= 3.12
-
-### INSTALL
-```bash
-pip install xn-auth
-```
-
----
-Made with ❤ on top of the [X-Model](https://github.com/XyncNet/x-model).

xn_auth-0.2.55/x_auth/exceptions.py

@@ -1,5 +0,0 @@
-from jwt import ExpiredSignatureError
-
-
-class ExpiredSignature(Exception):
-    def __init__(self, _uid: int, _encoded_token: str, _e: ExpiredSignatureError): ...