Metadata-Version: 2.4
Name: liteauth
Version: 0.1.6
Summary: Python 异步权限认证框架，受 Sa-Token 启发 — 多账号体系、JWT、OAuth2、SSO
Project-URL: Homepage, https://gitee.com/YueXia_1/liteauth
Project-URL: Repository, https://gitee.com/YueXia_1/liteauth
Project-URL: Documentation, https://gitee.com/YueXia_1/liteauth
Author-email: YueJian <yuexia@example.com>
License: Apache-2.0
License-File: LICENSE
Keywords: auth,authentication,fastapi,jwt,oauth2,sa-token,sso
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cashews>=7.5.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.13.4
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: hiredis>=3.4.0; extra == 'all'
Requires-Dist: orjson>=3.11.9; extra == 'all'
Requires-Dist: redis<6.0,>=5.0; extra == 'all'
Requires-Dist: uvicorn>=0.24.0; extra == 'all'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Requires-Dist: uvicorn>=0.24.0; extra == 'fastapi'
Provides-Extra: orjson
Requires-Dist: orjson>=3.11.9; extra == 'orjson'
Provides-Extra: redis
Requires-Dist: hiredis>=3.4.0; extra == 'redis'
Requires-Dist: redis<6.0,>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

# liteauth

> Python 异步权限认证框架，受 [Sa-Token](https://github.com/dromara/sa-token) 启发。

支持多账号体系、JWT（Simple / Mixin / Stateless）、OAuth2 服务端、SSO、Session 管理、角色/权限校验、踢人/顶号/封禁等能力。

## 设计原则

- **Core 无框架依赖** — 核心认证逻辑与 FastAPI / Flask / Django 解耦
- **Async first** — 全异步设计，原生适配 FastAPI / Starlette
- **多账号体系** — 一个系统多套用户表（`user` / `admin` / `merchant`），各自独立认证
- **可插拔存储** — Memory / Redis 自由切换，也可实现自定义 Store
- **JWT 可选** — 三种模式（Simple / Mixin / Stateless）按需选用

## 快速开始

```python
from liteauth import SaManager
from liteauth.core.config import SaTokenConfig
from liteauth.store.memory import MemoryStore

sa = SaManager()
sa.init(config=SaTokenConfig(), store=MemoryStore())
user_auth = sa.create_logic("user")

pair = await user_auth.login("10001")
token = pair.access_token                     # 统一 TokenPair（基础模式 refresh_token 为 None）
login_id = await user_auth.get_login_id_by_token(token)  # "10001"
```

## JWT Stateless 双 Token（access + refresh）

Stateless 模式完全无状态（不依赖任何 Store），登录返回 `TokenPair`：

```python
from liteauth.plugin.jwt import JwtConfig, JwtMode, JwtStatelessAuthLogic
from liteauth.core.config import SaTokenConfig

auth = JwtStatelessAuthLogic(
    login_type="user",
    config=SaTokenConfig(),
    jwt_config=JwtConfig(
        mode=JwtMode.STATELESS,
        secret_key="your-secret",
        jwt_access_token_timeout=3600,    # access 短效（秒）
        jwt_refresh_token_timeout=604800, # refresh 有限（秒）
        enable_refresh_token=True,        # False 时只签发 access
    ),
)

# 登录 → TokenPair(access_token, refresh_token, token_type, expires_in, ...)
pair = await auth.login("10001")
login_id = await auth.get_login_id_by_token(pair.access_token)  # "10001"

# 刷新 → 新 token 对（纯无状态，不依赖存储）
new_pair = await auth.refresh(pair.refresh_token)
```

安全模型说明（纯无状态取舍）：
- access 泄漏危害窗口 = `jwt_access_token_timeout`（短）
- refresh 泄漏危害窗口 = `jwt_refresh_token_timeout`（有限）
- 不依赖存储 ⇒ 无法作废旧 token / 检测重放，`logout` 仅清客户端缓存
- `get_login_id_by_token` 会拒绝 refresh token（校验 `token_use` claim）

## FastAPI 集成

```python
from fastapi import FastAPI, Depends
from liteauth.integration.fastapi.dependency import require_login, require_role

app = FastAPI()
sa.init_app(app)

@app.get("/me", dependencies=[Depends(require_login("user"))])
async def me():
    return {"msg": "已登录"}

@app.get("/admin", dependencies=[Depends(require_role("admin", auth="user"))])
async def admin():
    return {"msg": "管理员"}
```

### 路由中间件方式

```python
from liteauth.core.router import SaRouter
from liteauth.integration.fastapi.middleware import SaRouterMiddleware

router = SaRouter()
router.match("/api/admin/**").check(lambda ctx: admin_auth.check_login(ctx))
app.add_middleware(SaRouterMiddleware, sa_router=router)
```

## 安装

```bash
pip install liteauth

# 带 FastAPI 集成
pip install liteauth[fastapi]

# 带 Redis 存储
pip install liteauth[redis]

# 全量
pip install liteauth[all]
```

## 项目结构

```
liteauth/
├── core/           # 核心认证逻辑（无框架依赖）
│   ├── logic.py    # AuthLogic — 认证逻辑实现
│   ├── config.py   # SaTokenConfig — 全局配置
│   ├── session.py  # SaSession — 会话管理
│   ├── router.py   # SaRouter — 路由鉴权器
│   └── ...
├── store/          # 存储层抽象
│   ├── base.py     # Store 协议
│   ├── memory.py   # MemoryStore
│   └── redis.py    # RedisStore
├── integration/    # Web 框架集成
│   └── fastapi/    # FastAPI Depends / Middleware
├── plugin/         # 插件
│   ├── jwt/        # JWT Simple / Mixin / Stateless
│   ├── oauth2/     # OAuth2 服务端
│   └── sso/        # SSO 单点登录
├── strategy/       # 可替换策略
│   ├── key_builder.py  # Redis key 命名规则
│   └── token.py        # Token 生成策略
└── manager.py      # SaManager 全局管理器
```

## 许可证

Apache-2.0
