Metadata-Version: 2.4
Name: turbo-agent-auth
Version: 0.1.10rc1
Summary: Turbo Agent 授权管理库，支持基于平台授权方法与秘钥的登录、刷新与请求鉴权
Project-URL: Homepage, https://example.com/turbo-agent
Author-email: sherlet <wuzeilmt@gmail.com>
Requires-Python: <3.14,>=3.10
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.9.2
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: turbo-agent-core>=0.1.10rc1
Description-Content-Type: text/markdown

# turbo-agent-auth

Turbo Agent 授权管理库。提供基于 `turbo-agent-core` 中定义的 `Platform`、`AuthMethod`、`Secret` 数据模型，执行多步登录流程、凭据刷新、请求鉴权注入等能力。

## 定位

- **纯库**，不包含数据库、HTTP 服务等基础设施依赖
- 不做凭据持久化——只负责授权流程的执行与 HTTP 请求的鉴权注入
- 存储由上层模块（cloud / store）负责

## 核心能力

1. **登录流程执行** (`AuthFlowExecutor`)：基于 `AuthMethod.loginFlow` 定义的多步模板，渲染占位符、发送请求、解析响应、提取凭据
2. **同步/异步授权客户端** (`AuthClient` / `AsyncAuthClient`)：封装 Platform + AuthMethod + Secret，提供 `login()` / `refresh()` / `request()` 等方法
3. **请求鉴权注入** (`BaseAuthClient.prepare_http()`)：根据 `authFieldPlacements` 将 Token/Cookie/APIKey 注入到 HTTP 请求的 Header/Query/Cookie/Body 中
4. **默认授权模板** (`get_default_schemas()`)：内置 JWT、OAuth1/2、APIKey、Cookies、SMTP、POP3 的默认字段与流程模板
5. **SMTP/POP3 邮件支持** (`AuthClient.smtp_send()` / `AuthClient.pop3_fetch()`)

## 安装

```bash
uv add turbo-agent-auth
```

## 快速使用

```python
from turbo_agent_core.schema.external import Platform, AuthMethod, Secret
from turbo_agent_auth import AuthClient, AsyncAuthClient

# 构造平台、授权方式、秘钥实例（通常从 store 读取）
platform = Platform(...)
auth_method = AuthMethod(...)
secret = Secret(...)

# 同步客户端
client = AuthClient(platform, auth_method, secret)
client.login()  # 执行登录流程，更新 secret.credential
resp = client.get("/api/some-endpoint")  # 自动注入鉴权信息

# 异步客户端
async_client = AsyncAuthClient(platform, auth_method, secret)
await async_client.login()
resp = await async_client.get("/api/some-endpoint")
```
