0 Fork 0

Files

T

胡绍康andCopilot c79a173c03 docs: api.md 补充 raw/wait-message 独立安全风险说明段落

- /messages/{id}/raw: 原始内容风险、无脱敏、公网应禁用
- /wait-message: 同步轮询线程占用、并发耗尽风险、P2 解耦计划
- TODO-00008 第8节全部勾选完成（6/6）

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

2026-03-11 21:39:21 +08:00

21 KiB

Raw Blame History

API 文档

对外开放 API

本文档对应当前项目已实现的 /api/external/* 只读接口。

适用范围：

本地化部署
单实例
单可信调用方
内网或受控访问环境

当前版本不建议直接公网暴露。原因见：

docs/BUG/BUG-00013-对外开放API公网暴露风险与可用性缺口.md

如需机器可读规范，可同时参考：

docs/FD/OPENAPI-00008-对外验证码与邮件读取开放API.yaml

一、接口创建结论

1.1 当前已创建的接口

当前 P0 范围内，对外功能接口已经落地，不再需要新增同类查询接口：

分类	方法	路径	状态	说明
Messages	`GET`	`/api/external/messages`	已创建	获取邮件列表
Messages	`GET`	`/api/external/messages/latest`	已创建	获取最新匹配邮件
Messages	`GET`	`/api/external/messages/{message_id}`	已创建	获取邮件详情
Messages	`GET`	`/api/external/messages/{message_id}/raw`	已创建	获取邮件 RAW 内容
Verification	`GET`	`/api/external/verification-code`	已创建	提取最新验证码
Verification	`GET`	`/api/external/verification-link`	已创建	提取最新验证链接
Verification	`GET`	`/api/external/wait-message`	已创建	等待新邮件到达
System	`GET`	`/api/external/health`	已创建	外部健康检查
System	`GET`	`/api/external/capabilities`	已创建	查询开放能力
System	`GET`	`/api/external/account-status`	已创建	查询邮箱账号状态

1.2 配套但不是新建开放接口的后台接口

以下接口用于管理员配置 external_api_key，属于现有后台接口扩展，不属于开放接口本身：

方法	路径	登录要求	说明
`GET`	`/api/settings`	需要后台登录	返回 `external_api_key_set`、`external_api_key_masked`
`PUT`	`/api/settings`	需要后台登录	保存或清空 `external_api_key`

1.3 当前不建议继续新增的接口

P0 阶段不建议再新增以下业务接口：

邮件删除、标记已读、移动邮件等写接口
附件下载、附件元数据开放接口
Webhook / 回调通知接口
多调用方 API Key 管理接口

原因是当前目标是“受控私有接入闭环”，不是开放平台化扩张。

1.4 后续阶段可能补充的能力

后续如果进入 P1/P2，可优先补的是能力控制，而不是继续堆新路径：

阶段	类型	是否已定义为独立接口	说明
P1	公网模式、IP 白名单、限流	否	更适合加在鉴权层和安全层
P1	动态上游探测	否	优先增强现有 `/health`、`/account-status` 返回字段
P2	`wait-message` 解耦	否	先做后台轮询与缓存，再决定是否新增异步接口
P2	多 API Key / 范围授权	否	优先落在设置与鉴权模型，不急于新增公开路径

结论：

当前需要创建的核心开放接口：无。
当前需要补齐的是正式接口文档与后续阶段边界说明。

二、通用规则

2.1 Base URL

本地开发：

http://localhost:5000

生产部署：

https://your-domain.example.com

2.2 鉴权方式

所有 /api/external/* 接口统一使用请求头：

X-API-Key: your-api-key

限制：

仅支持 Header 中的 X-API-Key
不支持 query 参数中的 api_key
未配置 external_api_key 时，统一返回 403 API_KEY_NOT_CONFIGURED

2.3 通用成功响应

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {}
}

2.4 通用失败响应

{
  "success": false,
  "code": "INVALID_PARAM",
  "message": "参数错误",
  "data": null
}

2.5 通用错误码

错误码	HTTP 状态码	含义
`UNAUTHORIZED`	`401`	未提供或提供了错误的 `X-API-Key`
`API_KEY_NOT_CONFIGURED`	`403`	系统未配置对外 API Key
`INVALID_PARAM`	`400`	参数不合法
`ACCOUNT_NOT_FOUND`	`404`	指定邮箱账号不存在
`MAIL_NOT_FOUND`	`404`	未找到匹配邮件
`VERIFICATION_CODE_NOT_FOUND`	`404`	未找到验证码
`VERIFICATION_LINK_NOT_FOUND`	`404`	未找到验证链接
`PROXY_ERROR`	`502`	代理连接失败
`UPSTREAM_READ_FAILED`	`502`	Graph / IMAP 均读取失败
`INTERNAL_ERROR`	`500`	服务内部错误

2.6 通用查询参数

大多数邮件类接口共用以下参数：

参数	类型	必填	默认值	说明
`email`	string	是	无	目标邮箱地址
`folder`	string	否	`inbox`	`inbox` / `junkemail` / `deleteditems`
`from_contains`	string	否	空	发件人模糊匹配
`subject_contains`	string	否	空	主题模糊匹配
`since_minutes`	int	否	视接口而定	最近 N 分钟内邮件

分页相关参数仅 messages 使用：

参数	类型	必填	默认值	说明
`skip`	int	否	`0`	跳过条数，必须 `>=0`
`top`	int	否	`20`	返回条数，范围 `1-50`

2.7 接口版本与兼容策略

当前对外接口未单独引入 /v1 前缀，当前文档默认描述的是：

P0 受控私有接入版本
路径基线统一为 /api/external/*

兼容策略如下：

优先字段扩展，不轻易改路径
- P1 / P2 优先通过新增响应字段增强能力
- 不轻易修改现有接口 URL
保持响应主结构稳定
- 统一保持 success / code / message / data
- 调用方不应依赖未文档化的内部字段
破坏性变更才进入新版本
- 若后续必须改变鉴权方式、主响应结构或请求语义，建议新增 /api/external/v2/*
当前高风险接口不承诺长期不变
- /api/external/wait-message
- /api/external/messages/{message_id}/raw
- 这两个接口在进入公网模式时可能被限制、降级或替换

2.8 后续接口演进原则

为了避免接口碎片化，后续演进默认遵循以下原则：

P1 优先增强现有接口字段，不优先新增路径
- health 增加真实探测结果
- capabilities 增加当前模式与限制信息
- account-status 增加探测摘要
P1 的安全治理优先放在安全层，而不是业务接口层
- 公网模式
- IP 白名单
- 限流
- 高风险接口分级
P2 只有在同步模型无法满足要求时，才考虑新增异步接口
- wait-message 优先内部解耦
- 不默认承诺新增异步公开路径

三、快速示例

3.1 健康检查

curl -H "X-API-Key: your-api-key" \
  "http://localhost:5000/api/external/health"

3.2 读取邮件列表

curl -H "X-API-Key: your-api-key" \
  "http://localhost:5000/api/external/messages?email=user@outlook.com&folder=inbox&top=10"

3.3 提取验证码

curl -H "X-API-Key: your-api-key" \
  "http://localhost:5000/api/external/verification-code?email=user@outlook.com&subject_contains=verify&since_minutes=10"

四、Messages 类接口

4.1 `GET /api/external/messages`

用途：获取指定邮箱的邮件列表。

附加参数：

参数	类型	必填	默认值	说明
`skip`	int	否	`0`	分页偏移
`top`	int	否	`20`	返回数量，范围 `1-50`

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "emails": [
      {
        "id": "msg-1",
        "email_address": "user@outlook.com",
        "from_address": "noreply@example.com",
        "subject": "Your verification code",
        "content_preview": "Your code is 123456",
        "has_html": false,
        "timestamp": 1772961600,
        "created_at": "2026-03-08T12:00:00Z",
        "is_read": false,
        "method": "Graph API"
      }
    ],
    "count": 1,
    "has_more": false
  }
}

4.2 `GET /api/external/messages/latest`

用途：获取符合筛选条件的最新一封邮件。

成功响应中的 data 即单条 MessageSummary：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "id": "msg-new",
    "email_address": "user@outlook.com",
    "from_address": "noreply@example.com",
    "subject": "Target mail",
    "content_preview": "Your code is 123456",
    "has_html": false,
    "timestamp": 1772961600,
    "created_at": "2026-03-08T12:00:00Z",
    "is_read": false,
    "method": "Graph API"
  }
}

4.3 `GET /api/external/messages/{message_id}`

用途：获取单封邮件详情。

路径参数：

参数	类型	必填	说明
`message_id`	string	是	邮件 ID

说明：

该接口仍需通过 query 参数传入 email
folder 为可选提示参数，默认 inbox

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "id": "msg-1",
    "email_address": "user@outlook.com",
    "from_address": "noreply@example.com",
    "to_address": "user@outlook.com",
    "subject": "Your verification code",
    "content": "Your code is 123456",
    "html_content": "<p>Your code is 123456</p>",
    "raw_content": "RAW MIME CONTENT",
    "timestamp": 1772961600,
    "created_at": "2026-03-08T12:00:00Z",
    "has_html": true,
    "method": "Graph API"
  }
}

4.4 `GET /api/external/messages/{message_id}/raw`

用途：只返回邮件 RAW 内容，便于编码和解析排查。

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "id": "msg-1",
    "email_address": "user@outlook.com",
    "raw_content": "MIME-Version: 1.0\r\nraw test",
    "method": "Graph API"
  }
}

注意：

该接口返回高敏感原始内容
当前仅建议在受控私有环境下使用
若未来进入公网模式，该接口应作为默认受限接口处理

⚠️ 安全风险说明

/api/external/messages/{message_id}/raw 返回未经过滤的邮件原始内容（完整 MIME 正文），可能包含敏感信息、附件二进制数据或恶意脚本。

当前版本定位：仅面向受控私有接入场景（单实例、单可信调用方、内网部署）。

风险点：

原始内容无字段级脱敏，调用方须自行处理展示安全

当前无独立的访问频率限制

若部署在公网，该接口应优先禁用或加入 IP 白名单保护（P1 计划）

五、Verification 类接口

5.1 `GET /api/external/verification-code`

用途：从符合条件的最新邮件中提取验证码。

附加参数：

参数	类型	必填	默认值	说明
`code_length`	string	否	空	例如 `4-8` 或 `6-6`
`code_regex`	string	否	空	自定义验证码正则
`code_source`	string	否	`all`	`subject` / `content` / `html` / `all`

特别说明：

未显式传入 since_minutes 时，该接口默认只扫描最近 10 分钟的邮件

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "verification_code": "123456",
    "verification_link": "",
    "links": [],
    "formatted": "123456",
    "match_source": "content",
    "confidence": "high",
    "email": "user@outlook.com",
    "matched_email_id": "msg-1",
    "from": "noreply@example.com",
    "subject": "Your verification code",
    "received_at": "2026-03-08T12:00:00Z",
    "method": "Graph API"
  }
}

失败场景：

没有命中邮件：404 MAIL_NOT_FOUND
命中邮件但未提取到验证码：404 VERIFICATION_CODE_NOT_FOUND

5.2 `GET /api/external/verification-link`

用途：从符合条件的最新邮件中提取验证链接。

特别说明：

未显式传入 since_minutes 时，该接口默认只扫描最近 10 分钟的邮件

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "verification_code": "",
    "verification_link": "https://example.com/verify?token=abc",
    "links": [
      "https://example.com/verify?token=abc"
    ],
    "formatted": "https://example.com/verify?token=abc",
    "confidence": "high",
    "email": "user@outlook.com",
    "matched_email_id": "msg-1",
    "from": "noreply@example.com",
    "subject": "Please verify your email",
    "received_at": "2026-03-08T12:00:00Z",
    "method": "Graph API"
  }
}

失败场景：

没有命中邮件：404 MAIL_NOT_FOUND
命中邮件但未提取到验证链接：404 VERIFICATION_LINK_NOT_FOUND

5.3 `GET /api/external/wait-message`

用途：在超时时间内轮询等待符合条件的新邮件到达。

附加参数：

参数	类型	必填	默认值	说明
`timeout_seconds`	int	否	`30`	取值范围 `1-120`
`poll_interval`	int	否	`5`	轮询间隔，必须大于 `0` 且不超过 `timeout_seconds`

行为说明：

只返回调用开始后到达的新邮件
不会立即返回历史旧邮件
当前实现为同步轮询，请求线程会被占用

成功响应：

结构与 GET /api/external/messages/latest 一致

失败场景：

超时未命中：404 MAIL_NOT_FOUND
timeout_seconds 超限：400 INVALID_PARAM

⚠️ 安全风险说明

/api/external/wait-message 采用同步轮询实现，请求线程在等待期间被独占。

当前版本定位：仅面向受控私有接入场景，不建议在公网环境直接暴露。

风险点：

单次请求最长占用 120 秒线程，恶意并发可耗尽服务线程池

当前无独立的并发连接限制或调用频率限流

若部署在公网，该接口应优先禁用或加入限流保护（P1 计划）

P2 计划将同步轮询解耦为后台任务 + 状态查询模式

六、System 类接口

6.1 `GET /api/external/health`

用途：检查外部接口、服务进程和数据库是否基本可用。

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "status": "ok",
    "service": "outlook-email-plus",
    "version": "0.1.0-draft",
    "server_time_utc": "2026-03-08T12:00:00Z",
    "database": "ok"
  }
}

注意：

该接口当前偏向“服务与数据库存活”
不代表上游 Graph / IMAP 一定真实可读

6.2 `GET /api/external/capabilities`

用途：返回当前实例对外开放的能力清单。

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "service": "outlook-email-plus",
    "version": "0.1.0-draft",
    "features": [
      "message_list",
      "message_detail",
      "raw_content",
      "verification_code",
      "verification_link",
      "wait_message"
    ]
  }
}

6.3 `GET /api/external/account-status`

用途：检查指定邮箱账号是否存在，以及基础可读条件是否满足。

参数：

参数	类型	必填	说明
`email`	string	是	目标邮箱地址

成功响应示例：

{
  "success": true,
  "code": "OK",
  "message": "success",
  "data": {
    "email": "user@outlook.com",
    "exists": true,
    "account_type": "outlook",
    "provider": "outlook",
    "group_id": 1,
    "status": "active",
    "last_refresh_at": null,
    "preferred_method": "graph",
    "can_read": true
  }
}

注意：

can_read=true 仅表示基础配置字段存在
不等于已经完成真实拉信探测

七、管理员配置接口说明

7.1 `GET /api/settings`

用途：管理员登录后查看当前系统设置。

与开放 API 相关的返回字段：

字段	说明
`external_api_key_set`	是否已配置开放 API Key
`external_api_key_masked`	脱敏后的 Key 展示值

7.2 `PUT /api/settings`

用途：管理员登录后保存系统设置。

与开放 API 相关的请求字段：

字段	类型	说明
`external_api_key`	string	设置新的开放 API Key；传空字符串表示清空

说明：

配置写入后不会明文回显
实际存储会走现有敏感配置加密逻辑

八、接入建议

推荐接入顺序：

管理员登录后台，通过 /api/settings 配置 external_api_key
调用 /api/external/health 检查基础可用性
调用 /api/external/account-status?email=... 确认目标邮箱存在
视业务选择 /messages、/verification-code、/verification-link
仅在受控场景下使用 /wait-message 与 /raw

九、已知限制

当前仅适合受控私有接入，不建议直接公网暴露
当前只有单 external_api_key，默认具备读取本实例全部已配置邮箱的能力边界
wait-message 为同步轮询实现，不适合高并发公网场景
/api/external/health 与 /api/external/account-status 当前仍偏轻量，不等价于真实上游探测

十、当前接口问题与处理口径

下面这些不是“代码 Bug 列表”，而是调用方在使用接口时必须理解的当前接口问题。

10.1 `message_id` 不能单独定位账号

现状：

GET /api/external/messages/{message_id}
GET /api/external/messages/{message_id}/raw

仍然要求同时传 email 查询参数。

原因：

当前 message_id 的定位仍依赖邮箱上下文
系统没有建立“全局 message_id 到账号”的索引层

处理口径：

当前保留 ?email=... 作为必填上下文
P0/P1 不为此单独新增查询接口
如未来确实需要全局消息索引，再考虑在新版本中调整

10.2 `health` 与 `account-status` 当前是轻量自检，不是真实探测

现状：

/api/external/health 主要反映服务和数据库是否存活
/api/external/account-status 主要反映账号是否存在、基础配置是否完整

问题：

它们不能证明 Graph / IMAP 在当前时刻一定可读

处理口径：

当前文档明确按“轻量自检”解释这两个接口
P1 优先扩展字段，不优先新增同类接口

10.3 `/raw` 接口敏感度高

现状：

/api/external/messages/{message_id}/raw 可返回原始邮件内容

问题：

原始内容可能包含完整 MIME、头信息、HTML 或调试用敏感内容

处理口径：

当前仅建议在受控私有环境下使用
未来进入公网模式时，该接口默认应视为受限接口

10.4 `wait-message` 成本高

现状：

/api/external/wait-message 使用同步轮询
请求线程会在超时窗口内被占用

问题：

对单 worker 或低并发部署不友好
不适合作为长期公网高并发能力

处理口径：

当前允许在受控环境下保留
P1 若进入公网模式，应优先禁用或限制
P2 再考虑是否替换为异步模型

10.5 单 API Key 权限边界较粗

现状：

当前只有一个 external_api_key
默认可读取本实例全部已配置邮箱

问题：

不适合多调用方或复杂权限边界

处理口径：

当前仅按单可信调用方场景验收
P2 再做多 API Key 和范围授权

十一、后续阶段接口文档预留

本节用于说明后续如果进入 P1/P2，接口文档应优先怎么演进。

11.1 P1：优先扩展现有接口字段

`GET /api/external/health`

建议后续增加但当前不承诺的字段：

字段	含义
`upstream_probe_ok`	上游读取链路最近一次探测是否成功
`last_probe_at`	最近一次探测时间
`last_probe_error`	最近一次探测错误摘要
`public_mode`	当前是否处于公网模式

`GET /api/external/capabilities`

建议后续增加但当前不承诺的字段：

字段	含义
`public_mode`	当前模式是否为公网模式
`restricted_features`	当前被限制的接口能力
`rate_limit_enabled`	是否已启用限流

`GET /api/external/account-status`

建议后续增加但当前不承诺的字段：

字段	含义
`upstream_probe_ok`	最近一次真实读取探测结果
`probe_method`	探测所使用的读取方式
`last_probe_at`	最近探测时间
`last_probe_error`	最近探测错误摘要

11.2 P1：优先新增控制字段，不优先新增业务路径

P1 更推荐补的是控制能力，而不是新增更多邮件接口：

公网模式开关
来源 IP 白名单
限流
/wait-message 与 /raw 的接口分级

这些能力默认应体现在：

安全层
系统能力说明字段
部署文档

而不是优先新增新的业务 URL。

11.3 P2：只有在必要时才考虑新接口

如果 P2 阶段必须引入新的公开接口，建议优先满足以下条件：

现有同步接口已无法满足并发或稳定性要求
仅通过扩展字段无法表达新能力
新接口语义清晰，且不会和现有路径混淆

当前不提前承诺新增以下路径：

异步等待接口
多调用方管理接口
配额管理接口

如果未来必须新增，建议进入新版本或新增专门的管理域，而不是继续把所有能力堆在 /api/external/* 主业务路径下。

21 KiB Raw Blame History Unescape Escape

API 文档

对外开放 API

一、接口创建结论

1.1 当前已创建的接口

1.2 配套但不是新建开放接口的后台接口

1.3 当前不建议继续新增的接口

1.4 后续阶段可能补充的能力

二、通用规则

2.1 Base URL

2.2 鉴权方式

2.3 通用成功响应

2.4 通用失败响应

2.5 通用错误码

2.6 通用查询参数

2.7 接口版本与兼容策略

2.8 后续接口演进原则

三、快速示例

3.1 健康检查

3.2 读取邮件列表

3.3 提取验证码

四、Messages 类接口

4.1 GET /api/external/messages

4.2 GET /api/external/messages/latest

4.3 GET /api/external/messages/{message_id}

4.4 GET /api/external/messages/{message_id}/raw

五、Verification 类接口

5.1 GET /api/external/verification-code

5.2 GET /api/external/verification-link

5.3 GET /api/external/wait-message

六、System 类接口

6.1 GET /api/external/health

6.2 GET /api/external/capabilities

6.3 GET /api/external/account-status

七、管理员配置接口说明

7.1 GET /api/settings

7.2 PUT /api/settings

八、接入建议

九、已知限制

十、当前接口问题与处理口径

10.1 message_id 不能单独定位账号

10.2 health 与 account-status 当前是轻量自检，不是真实探测

10.3 /raw 接口敏感度高

10.4 wait-message 成本高

10.5 单 API Key 权限边界较粗

十一、后续阶段接口文档预留

11.1 P1：优先扩展现有接口字段

GET /api/external/health

GET /api/external/capabilities

GET /api/external/account-status

11.2 P1：优先新增控制字段，不优先新增业务路径

11.3 P2：只有在必要时才考虑新接口

21 KiB

Raw Blame History

4.1 `GET /api/external/messages`

4.2 `GET /api/external/messages/latest`

4.3 `GET /api/external/messages/{message_id}`

4.4 `GET /api/external/messages/{message_id}/raw`

5.1 `GET /api/external/verification-code`

5.2 `GET /api/external/verification-link`

5.3 `GET /api/external/wait-message`

6.1 `GET /api/external/health`

6.2 `GET /api/external/capabilities`

6.3 `GET /api/external/account-status`

7.1 `GET /api/settings`

7.2 `PUT /api/settings`

10.1 `message_id` 不能单独定位账号

10.2 `health` 与 `account-status` 当前是轻量自检，不是真实探测

10.3 `/raw` 接口敏感度高

10.4 `wait-message` 成本高

`GET /api/external/health`

`GET /api/external/capabilities`

`GET /api/external/account-status`