Metadata-Version: 2.4
Name: micosauth
Version: 0.1.0
Summary: Redis-based auth and session package for Python applications
Author-email: CharlieZhang <charlie@example.com>
License: MIT
Project-URL: Homepage, https://github.com/jiangbyte/micosauth
Project-URL: Documentation, https://github.com/jiangbyte/micosauth
Project-URL: Repository, https://github.com/jiangbyte/micosauth
Project-URL: Issues, https://github.com/jiangbyte/micosauth/issues
Keywords: auth,authentication,authorization,redis,fastapi,session,token
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
Classifier: Framework :: FastAPI
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.136.1
Requires-Dist: redis>=7.4.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.136.1; extra == "fastapi"
Requires-Dist: starlette>=0.37.2; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"

# micosauth 使用文档

`micosauth` 是一个基于 Redis 的通用认证鉴权包，当前版本核心模型是：

- 多 realm
- 基于 `login_id` 登录
- 默认 64 位字符串 token
- 支持多设备、多 token 策略控制
- 普通 token 与临时 token
- `MicosAuthUtil` 负责认证、鉴权、撤销、反查
- `MicosSessionUtil` 负责查询、统计、分布分析

## 1. 核心对象

- `MicosSetting`
  启动配置对象
- `MicosService`
  启动装配对象
- `MicosAuthUtil`
  主认证鉴权工具
- `MicosSessionUtil`
  会话查询统计工具
- `MicosTokenUtil`
  token 生成工具

## 2. 安装

```bash
pip install micosauth
```

如需 FastAPI 适配层：

```bash
pip install "micosauth[fastapi]"
```

## 3. 启动接入

```python
from micosauth import (
    MicosAuthUtil,
    MicosRealmSetting,
    MicosRedisSetting,
    MicosService,
    MicosSessionUtil,
    MicosSetting,
)

micos_setting = MicosSetting(
    redis=MicosRedisSetting(url="redis://:123456@127.0.0.1:6379/1"),
)

micos_service = MicosService(micos_setting)
micos_service.register_realm(MicosRealmSetting(realm_id="admin"))
micos_service.register_realm(MicosRealmSetting(realm_id="user"))

await micos_service.init()

micos_auth = MicosAuthUtil(micos_service)
micos_session = MicosSessionUtil(micos_service)
```

## 4. Realm 配置

`MicosRealmSetting` 当前支持的核心策略项：

```python
MicosRealmSetting(
    realm_id="admin",
    token_name="Authorization",
    token_ttl_seconds=2592000,
    temp_token_ttl_seconds=300,
    allow_multi_device_login=True,
    keep_old_token_on_same_device_login=False,
    keep_old_token_on_new_device_login=True,
    max_devices_per_login_id=2,
    max_tokens_per_login_id=5,
    max_tokens_per_device=1,
)
```

字段含义：

- `allow_multi_device_login`
  是否允许多设备同时登录
- `keep_old_token_on_same_device_login`
  同设备再次登录时是否保留旧 token
- `keep_old_token_on_new_device_login`
  新设备登录时是否保留其他设备旧 token
- `max_devices_per_login_id`
  每个 `login_id` 允许的最大设备数，`0` 表示不限制
- `max_tokens_per_login_id`
  每个 `login_id` 允许的最大 token 数，`0` 表示不限制
- `max_tokens_per_device`
  每个设备允许的最大 token 数，`0` 表示不限制

## 5. 注册 AccessProvider

使用方需要自己实现权限、角色、数据范围获取逻辑。

```python
from micosauth import MicosAccessProvider


class AdminAccessProvider:
    async def get_roles(self, realm_id: str, login_id: str) -> list[str]:
        return ["ADMIN"]

    async def get_permissions(self, realm_id: str, login_id: str) -> list[str]:
        return ["sys:user:view", "sys:session:page"]

    async def get_data_scopes(self, realm_id: str, login_id: str) -> list[str]:
        return ["ALL"]

    async def get_extra(self, realm_id: str, login_id: str) -> dict:
        return {"nickname": "管理员"}
```

注册方式：

```python
micos_service.register_access_provider("admin", AdminAccessProvider())
```

## 6. 登录与普通 token

登录只需要 `login_id`，推荐同时传入 `device_id`：

```python
result = await micos_auth.login(
    "admin",
    "1001",
    device_id="pc",
    extra={"nickname": "管理员"},
)
```

返回示例：

```python
{
    "token": "...64位字符串...",
    "login_id": "1001",
    "realm_id": "admin",
    "device_id": "pc",
    "expires_at": "2026-06-14T12:00:00+00:00",
}
```

说明：

- 当前模型中不再暴露独立 `session_id`
- 会话主体围绕 `realm_id + login_id` 组织
- token 是登录明细单元

## 7. 鉴权与反查

```python
is_valid = await micos_auth.is_token_valid(token, "admin")
inspect_result = await micos_auth.inspect_token(token, "admin")
login_id = await micos_auth.get_login_id_by_token(token, "admin")
roles = await micos_auth.get_roles("admin", "1001")
permissions = await micos_auth.get_permissions("admin", "1001")
data_scopes = await micos_auth.get_data_scopes_by_login_id("admin", "1001")
```

## 8. 临时 token

创建：

```python
temp = await micos_auth.create_temp_token(
    "admin",
    temp_id="file-1001",
    type="download",
    time=300,
    extra={"filename": "report.xlsx"},
)
```

校验：

```python
ok = await micos_auth.verify_temp_token(
    temp["token"],
    "admin",
    type="download",
)
```

## 9. 会话查询与统计

当前查询模型：

- `session` 是 `login_id` 级聚合
- `token` 是具体登录明细
- `device` 是 token 分组维度

```python
sessions = await micos_session.list_sessions("admin")
page = await micos_session.page_sessions("admin", current=1, size=20)
login_session = await micos_session.get_session("admin", "1001")
tokens = await micos_session.list_tokens("admin", "1001")
device_tokens = await micos_session.list_device_sessions("admin", "1001", "pc")
device_summaries = await micos_session.list_device_summaries("admin", "1001")

online_count = await micos_session.count_online_sessions("admin")
login_token_count = await micos_session.count_login_id_sessions("admin", "1001")
device_token_count = await micos_session.count_device_tokens("admin", "1001", "pc")

analysis = await micos_session.get_analysis()
chart = await micos_session.get_chart_data(days=7)
distribution = await micos_session.get_realm_distribution()
```

统计对象说明：

- `get_analysis()`
  返回总登录数、总 token 数、总设备数、最近一小时新增 token 数
- `get_chart_data(days=7)`
  返回按天统计的 token 创建趋势
- `get_realm_distribution()`
  返回各 realm 的登录数、token 数、设备数分布
- `list_device_summaries("admin", "1001")`
  直接返回某个 `login_id` 下各设备摘要，包括 token 数、最近登录时间、最近访问时间

## 10. 撤销与下线

```python
await micos_auth.revoke_token("admin", token)
await micos_auth.revoke_login("admin", "1001")
await micos_auth.kickout_login_id("admin", "1001")
await micos_auth.kickout_device("admin", "1001", "pc")
```

兼容接口：

```python
await micos_auth.logout_current("admin", token)
await micos_auth.logout_login_id("admin", "1001")
await micos_auth.logout_device("admin", "1001", "pc")
```

## 11. Redis 存储模型

当前 Redis 主结构围绕 `realm_id + login_id`：

- `micosauth:{realm_id}:{login_id}:session`
  登录主体聚合数据
- `micosauth:{realm_id}:{login_id}:tokens`
  token 明细 `HASH`
- `micosauth:{realm_id}:{login_id}:device_tokens:{device_id}`
  设备维度 token 明细 `HASH`
- `micosauth:{realm_id}:token_lookup:{token}`
  token 反查 `login_id`
- `micosauth:{realm_id}:login_index`
  realm 级 login 分布索引
- `micosauth:{realm_id}:token_index`
  token 过期索引
- `micosauth:{realm_id}:created_index`
  token 创建时间索引
- `micosauth:{realm_id}:temp:{token}`
  临时 token

## 12. FastAPI 接入

```python
from fastapi import FastAPI
from micosauth.adapters.fastapi import build_micosauth_lifespan, install_fastapi_auth

app = FastAPI(lifespan=build_micosauth_lifespan(micos_service))
install_fastapi_auth(app, micos_service)
```

说明：

- FastAPI dependency 必须显式传 `realm`
- decorator 必须显式传 `realm`
- middleware 不做默认自动认证
- `micosauth` 不负责猜测 realm

示例：

```python
from fastapi import Depends
from micosauth.adapters.fastapi import require_login_dep


@app.get("/admin/me", dependencies=[Depends(require_login_dep(realm="admin"))])
async def admin_me():
    return {"ok": True}
```

## 13. OR / AND 鉴权模式

角色和权限校验都支持：

- `AND`
- `OR`
- 权限支持通配符匹配

```python
await micos_auth.require_roles(token, ["ADMIN", "AUDITOR"], "admin", mode="AND")
await micos_auth.require_permissions(token, ["sys:user:*", "sys:log:view"], "admin", mode="OR")
```

## 14. 当前状态

当前版本已经完成：

- Redis 真测
- FastAPI 集成真测
- 多 realm 接入真测
- 多设备、多 token 策略真测
- 设备摘要查询真测
- 角色、权限 `AND/OR` 模式测试
- 权限通配符测试

