micosauth 0.1.0__tar.gz

micosauth-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include docs *.md

micosauth-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+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` 模式测试
+- 权限通配符测试
+

micosauth-0.1.0/README.md

@@ -0,0 +1,319 @@
+# 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` 模式测试
+- 权限通配符测试
+

micosauth-0.1.0/docs/PUBLISH.md

@@ -0,0 +1,44 @@
+# micosauth 发布说明
+
+## 1. 发布前检查
+
+发布到 PyPI 之前，至少完成以下检查：
+
+1. 运行单元测试
+2. 确认 `python -m compileall micosauth` 通过
+3. 检查 `pyproject.toml` 已包含 `micosauth*`
+4. 检查 `micosauth/docs/README.md` 是否同步最新用法
+5. 确认版本号
+6. 确认依赖项
+
+## 2. 当前项目中的打包注意事项
+
+当前仓库主项目名仍然是 `hei-fastapi`，不是独立的 `micosauth` 包仓库。
+
+这意味着当前状态下：
+
+- `micosauth` 已经可以被主项目一起打包
+- 但还不是独立发布到 PyPI 的最终形态
+
+如果要正式作为独立包发布，建议后续拆分为独立仓库，并调整：
+
+- `[project].name`
+- `[project].description`
+- README
+- classifiers
+- 可选依赖
+
+## 3. 当前已完成的基础验证
+
+- `pytest -q micosauth/tests`
+- `python -m compileall micosauth`
+
+## 4. 建议的下一步
+
+正式发布前，建议继续补齐：
+
+- Redis 集成测试
+- FastAPI 适配层测试
+- 临时 token 集成测试
+- 撤销 / 下线 / 多设备多 token 行为测试
+- PyPI 元数据整理