# 授权管理模块

## 更新记录
- 2025-11-18：多秘钥 + 登录刷新流程、Prisma JSON 序列化修复、X 平台 OAuth1 与微信示例落地。
- 2025-11-19：登录执行轨迹（steps + parsed + final）、首次创建即授权返回执行详情、`autoLoginEnabled=false` 不持久化登录表单、失败自动失效与通知标记、Secret 唯一性调整（仅 id 唯一）、失效与通知接口、统一日志分级与敏感字段调试开关(`LOG_SENSITIVE_DEBUG`)、补充秘钥生命周期文档引用。
- 2025-11-20：新增 per-request 代理执行能力（`proxy` 参数支持 HTTP/HTTPS/SOCKS），登录/首次创建执行/更新并执行/带轨迹登录均可指定单次代理；引入依赖 `httpx[socks]` 支持 `socks5://`；`docs/manuals.md` 增补使用示例。
- 2025-11-20：启动可配置 API Key (`AUTH_API_KEY` / CLI `--api-key`) 保护 `/v1/*` 路由（`Authorization: Bearer <key>`），新增 `Dockerfile` 与 `docker-compose.yml` 示例方便部署。
- 2025-11-26：支持 `multipart/form-data` 类型的登录请求体。当 `Content-Type` 包含 `multipart/form-data` 时，`body_template`（字典）将被转换为 multipart 格式发送，且自动处理 boundary。
- 2025-11-27：新增 `POST /auth-methods/{id}/pre-auth` 接口，支持在不创建 Secret 的情况下执行预授权登录流程并返回执行轨迹。
- 2025-11-27：Secret 创建与更新逻辑调整：当 `autoLoginEnabled` 为 `False` 时，不校验 `loginPayload` 格式，也不强制要求提供 `loginPayload`，仅存储授权数据 (`data`)。

## 协作约定
- 依赖统一由 `uv` 管理，新增第三方包时执行 `uv add`，不要直接改写 `pyproject.toml`。
- 如未额外说明，开发时可暂不落地自测，但需在 `README.md` 里同步使用方式并把更新记录写在文档开头。
- 已有接口若有变动，请在 `README.md` 的原位置同步说明，避免分散。
- 回复与文档均保持中文；提交实现后，用一句 100 字左右的中文描述记录新开发功能（方便后续追溯）。
- 遇到未定义的业务需求不要自行臆测，等待进一步指令；发现异常改动需先与需求方确认。
- 所有聊天沟通内容均使用中文！所有聊天沟通内容均使用中文！所有聊天沟通内容均使用中文！

## 项目概览
`turbo-agent-auth` 提供 turbo-agent 平台的统一授权管理能力，围绕 `Platform`、`AuthMethod`、`Secret` 三类模型存储与解析多种平台凭证。服务以 FastAPI 提供 HTTP 接口，Typer 作为 CLI 入口，Prisma 负责 PostgreSQL 数据访问，并通过 YAML 模板定义各类授权流程的默认行为。

## 当前能力总览
- FastAPI 应用：内置 `/health`、`/v1/ping` 及授权管理主路由，启动时自动加载默认授权模板并连接数据库。
- 授权模型：`Platform`、`AuthMethod`、`Secret` 均由外部 ID 驱动，支持 1:N 密钥、标签、多账号、凭证同意等扩展字段。
- 授权流程：`loginFlow` / `refreshFlow` / `responseMapping` 抽象为配置数据，按需覆盖或继承默认模板；自动计算秘钥有效期。
- 密钥维护：支持按名称 upsert、列表、按 ID/名称查询、局部更新、提醒记录，便于后续刷新与监控策略；新增“失效标记/已通知标记”。
- 默认模板：内置 JWT、OAuth1、OAuth2、APIKey、Cookies、SMTP、POP3 七类模板，集中于 `config/auth_schemas.yaml`。
- 日志体系：基于 Loguru，统一封装 CLI 选项 / 环境变量，HTTP 中间件记录请求耗时，并兼容 Uvicorn/FastAPI 标准日志。
- 测试基线：提供健康检查与 ping 的 pytest 用例，快速验证服务可启动。

新增（执行可观测性与策略）：
- 登录可观测：支持“执行轨迹（steps + 请求快照 + 解析产物）”返回；
- 首次创建返回执行详情：`POST /auth-methods/{id}/secret` 返回 `secret + execution` 复合体；
- 手动登录可选返回轨迹：`POST /v1/secrets/{id}/login` / `/login/trace`；
- autoLogin 策略：`autoLoginEnabled=false` 时不持久化 `loginPayload`；需在登录接口即时提供；
- 失效管理：`/secrets/{id}/invalidate` 标记 `isValid=false`，`/invalid-notified` 标记是否已通知。

一句话变更记录（2025-11-19）：完成登录执行轨迹返回、首次创建即授权并返回详情、隐私模式不持久化登录表单、失败自动失效与通知标记、及相应路由补充。
一句话变更记录（2025-11-20）：支持在相关登录执行端点传入 `proxy`（HTTP/HTTPS/SOCKS）实现单次链路代理，不持久化；新增 `httpx[socks]` 依赖。
一句话变更记录（2025-11-20-APIKey+Docker）：新增启动 API Key 鉴权（Authorization: Bearer），并提供 Dockerfile 与 docker-compose 示例。

## 运行与调试
- 安装依赖：`uv sync`
- 本地运行 API：`uv run turbo-agent-auth serve run --host 0.0.0.0 --port 8000`
- 查看 CLI 帮助：`uv run turbo-agent-auth serve run --help`
- 必需环境变量：`DATABASE_URL=postgresql://user:pass@host:5432/dbname`
- Prisma 操作：
   - 生成客户端：`uv run python -m prisma generate`
   - 开发迁移：`uv run python -m prisma migrate dev`
   - 部署迁移：`uv run python -m prisma migrate deploy`
- 日志参数可通过 CLI（`--log-level`, `--json`, `--log-file`, `--rotation`, `--retention`）或对应环境变量配置。

## 模块结构要点
- `main.py` / `cli.py`：Typer 命令定义与 Uvicorn 启动逻辑。
- `app.py`：FastAPI 实例工厂、日志中间件、启动钩子（加载模板、连接 Prisma）。
- `api/routes.py`：REST 接口路由，提供平台、授权方式、秘钥、默认 schema、响应解析等能力。
- `services/auth_service.py`：业务实现，包括默认模板加载、CRUD、解析逻辑、秘钥生命周期处理。
- `schemas.py`：Pydantic 模型定义，请求/响应与内部校验格式统一。
- `logging.py`：Loguru 配置、标准库日志兼容。
- `config/auth_schemas.yaml`：各类授权方式默认字段、流程与解析配置。

## 数据模型（Prisma）
- `Platform`：`id`、`orgId`+`nameId` 联合唯一，描述平台元信息与可用状态。
- `AuthMethod`：关联平台，保存授权类型、描述、登录/刷新流程、默认有效期等；`platformId+name` 唯一约束。
- `Secret`：存储具体凭证数据、有效期、标签、刷新/提醒时间、登录表单（可选）、状态字段等；仅 `id` 唯一：
   - 字段要点：`data`、`expiresAt`、`authDataSources`、`loginPayload`（可选）、`autoLoginEnabled`、`isValid`（默认 true）、`invalidNotified`（默认 false）、`lastLoginAt/Status/Error`；
   - 唯一性变更：取消 `authMethodId+name` 唯一，查询/更新同名条目时取“同名最新一条”；
   - 安全策略：当 `autoLoginEnabled=false` 时不持久化 `loginPayload`。
- 枚举：`AuthType`（JWT/OAuth1/OAuth2/APIKey/Cookies/SMTP/POP3）、`KeyLocation`、`RequestMethod`。

## 默认模板使用说明
- 通过 `load_default_schemas()` 加载 YAML；首次使用时读入缓存。
- 创建授权方式时，如未显式提供 flow/schema/responseMapping，自动填充对应类型默认值。
- 模板支持占位符（如 `{{token_url}}`），在运行时由调用方根据字段值渲染。
- Cookies 模板支持从 `headers['Set-Cookie']` 或 `cookies` 字段解析多条 cookie。

## API 速览（`/v1` 前缀）
- `GET /ping`：服务可用性检查。
- `POST /platforms` / `GET /platforms` / `GET /platforms/{id}` / `PATCH /platforms/{id}`。
- `POST /auth-methods` / `GET /platforms/{platform_id}/auth-methods` / `GET /auth-methods/{id}` / `PATCH /auth-methods/{id}`。
- `GET /auth-types/default-schemas` / `GET /auth-types/default-schemas/{auth_type}`。
- `POST /auth-methods/{id}/secret`（创建/替换并尽量执行首次授权，返回 `SecretLoginWithExecution`，支持 `?proxy=` 单次代理）
- `POST /auth-methods/{id}/pre-auth`（执行预授权登录，不创建 Secret，返回 `LoginExecutionResult`）
- `GET /auth-methods/{id}/secret?name=` / `GET /auth-methods/{id}/secrets` / `GET /secrets/{secret_id}`
- `PATCH /secrets/{secret_id}`（仅更新） / `PATCH /secrets/{secret_id}/with-execution`（更新并返回执行轨迹，支持 `?proxy=` 单次代理）
- `POST /secrets/{secret_id}/login`（触发登录，body 可选 `proxy` 字段） / `POST /secrets/{secret_id}/login/trace`（触发登录并返回执行轨迹，body 可选 `proxy` 字段）
- `POST /secrets/{secret_id}/invalidate`（外部标记失效） / `POST /secrets/{secret_id}/invalid-notified`（标记是否已通知）
- `POST /secrets/{secret_id}/remind`（记录提醒） / `DELETE /secrets/{secret_id}`（删除）
- `POST /auth-methods/{id}/parse`：根据 `responseMapping` 提取令牌并计算到期时间，支持 body/headers/cookies。

接口使用建议与完整示例请参考 `docs/manuals.md` 的“秘钥生命周期与接口选择”。

## 日志与监控
- 所有请求经过中间件记录方法、路径、状态码、耗时（毫秒）。
- `setup_logging` 只在首次调用时生效，避免重复初始化；`patch_standard_logging` 将标准库、Uvicorn 日志转发到 Loguru。
- 日志可输出 JSON 或文本格式，可选文件写入与滚动规则。
- 级别策略：正常步骤/最终解析使用 INFO；失败/异常使用 ERROR；非 2xx 步骤状态（4xx）提升为 WARNING；敏感表单字段仅在 `LOG_LEVEL=DEBUG` 且 `LOG_SENSITIVE_DEBUG=1` 时输出原文，默认仅输出脱敏版本（DEBUG 级别）。
- 环境变量：`LOG_LEVEL` 控制整体级别；`LOG_FORMAT=json|plain` 控制格式；`LOG_SENSITIVE_DEBUG=1` 打开敏感原文调试；其余留空则不打印原文。

## 测试基线
- 核心用例位于 `tests/test_health.py`，验证 `/health` 与 `/v1/ping`。
- 运行命令：`uv run pytest -q`
- 如增量开发需补测试，请遵循 pytest 风格并复用 TestClient。

## 当前状态与后续
- 数据表与模型已迭代，包含 `isValid`、`invalidNotified`、取消 `Secret(authMethodId,name)` 唯一等改动，迁移已落在 `prisma/migrations/*`。
- 暂无新增需求待办，如需扩展请在此文档 `## 当前状态与后续` 追加条目并给出优先级。
- 最近一次对外接口操作示例（见终端历史）为 `POST /v1/auth-methods` 创建 OAuth2 授权方式，可作为联调参考。
- 2025-11-18：
   1) 修复 Prisma JSON 字段序列化导致的 GraphQL 解析错误，在 AuthMethod/Secret 相关写入操作中统一使用 `prisma.Json` 包装所有 dict/list 数据，避免 header 键名被拆分；
   2) 调整 Secret upsert 逻辑，改由关系 connect 赋值外键，确保创建流程兼容；
   3) 通过 API 完成 X 平台 OAuth1 授权方式与示例秘钥创建，验证 `authFieldsSchema`、`authFieldPlacements`、`authDataSources` 等字段的实际效果；
   4) 完成对微信授权方式的记录

- 2025-11-19（本次）：
   1) 登录执行可观测性：新增返回步骤级执行轨迹与请求快照；
   2) 首次创建即授权：`POST /auth-methods/{id}/secret` 返回 `secret+execution`；
   3) 新接口：`/secrets/{id}/login/trace`、`/secrets/{id}/with-execution`、`/secrets/{id}/invalidate`、`/secrets/{id}/invalid-notified`、`DELETE /secrets/{id}`；
   4) 策略：`autoLoginEnabled=false` 不持久化 `loginPayload`；调用登录接口时需即时提供；
   5) 失败即失效：登录失败会写入 `lastLoginError` 并置 `isValid=false,status=invalid,invalidNotified=false`。

## 整体设计（要点）
- 三层模型：`Platform`（归属）-`AuthMethod`（配置/流程）-`Secret`（凭证实例）。
- 配置驱动：`loginFlow`/`refreshFlow`/`responseMapping`/`authFieldPlacements` 描述“如何登录/解析/投放”。
- 上下文与注入：`requestPlacements` 串联登录阶段步骤间的上下文传递；最终凭证按 `authFieldPlacements` 注入业务请求。
- 可观测性：解析结果与字段来源写入 `Secret.authDataSources`；登录过程可返回步骤级轨迹，包含请求快照与解析键。
- 有效期：综合 token 字段与 cookies 过期，取最早者作为 `expiresAt`，并支持 `refreshBeforeSeconds`。
- 安全与策略：支持不持久化 `loginPayload`；失效/通知标记用于外部事件闭环与告警去重。
### 代理执行（Proxy 支持）
- 场景：需要经内网/出口受限/调试代理访问第三方登录接口。
- 适用端点：首次创建执行（`POST /auth-methods/{id}/secret?proxy=`）、更新并执行（`PATCH /secrets/{secret_id}/with-execution?proxy=`）、普通登录（`POST /secrets/{secret_id}/login` body `proxy`）、轨迹登录（`POST /secrets/{secret_id}/login/trace` body `proxy`）。
- 协议：`http://`、`https://`、`socks5://`（依赖 `httpx[socks]` 已加入）。
- 生命周期：仅当次调用有效；不写入数据库，不记录于 `Secret` 字段；后续需再次传入。
- 安全：避免持久化内部代理地址；表单字段仍按敏感日志策略控制输出；代理地址本身不脱敏（可在上层网关做过滤）。
- 示例：详见 `docs/manuals.md` 第 4.3 节附加代理示例。

## 重要参考文档
- 使用与设计手册（强烈推荐）：`docs/manuals.md`（含“秘钥生命周期与接口选择”与 curl 示例）
- 授权方式配置详解：`docs/auth_method.md`
- 示例：微信公众平台 `weixin.md`、X 平台 `x.md`、SMTP/POP3/Superset 在 `docs/examples/` 下
- 顶层说明与变更：`README.md`

## 已完成需求归档
1. 登录/授权获取支持即时代理执行（2025-11-20 实现）。
2. 启动可配置 API Key（`AUTH_API_KEY` / CLI `--api-key`，Bearer 格式）保护 `/v1/*`，新增 Dockerfile 与 docker-compose 示例（2025-11-20 实现）。

## 新增需求
（暂无，若有新增请在此追加并注明优先级）
