feat: v2.0.0 邮件接收架构改造 —— 移除 Node,Email Worker 直连 Console(docs/11)
- 两阶段接收:POST /internal/email/authorize(accept/reject/temporary_error)+ POST /internal/email/ingest(raw MIME 直传) - Worker-Console 协议:Authorization: WmailHub-Worker + timestamp/nonce/body-hash/HMAC,nonce 防重放,凭据撤销即时生效 - 数据模型:nodes/node_credentials -> cloudflare_accounts/worker_credentials(迁移 0003),emails/domains 归属 account_id - 接入流程 Connect Cloudflare Account:OAuth 自动同步域名 + 部署账号级 Email Worker + 签发 Worker 凭据;rotate 自动重部署 - 动态邮箱:创建/删除/禁用下一封邮件立即生效;拒绝码 DOMAIN_*/MAILBOX_*;超时/5xx 不伪装成邮箱不存在 - 删除 node/ 目录、旧 /api/internal/nodes 协议、ingress/enrollment 概念;dev.ts 简化为 console + email worker 双进程 - 前端:账号页 Email Worker/凭据管理,设置窗口移除默认 Ingress,仪表盘/文案同步;版本 2.0.0 - 测试 62 项全过(新增 authorize 决策矩阵 + Worker 两阶段临时错误语义);本机虚拟 E2E 12 场景全通 - docs 00-10 同步改写;README 更新
This commit is contained in:
+22
-11
@@ -1,10 +1,11 @@
|
||||
# Webhook、API 与 MCP
|
||||
|
||||
Webhook、API、MCP 全部属于 Console,Node 不实现这些能力。
|
||||
Webhook、API、MCP 全部属于 Console,Email Worker 不实现这些能力。
|
||||
|
||||
## Webhook
|
||||
## Webhook(三级:邮箱 -> 域名 -> 全局)
|
||||
|
||||
邮件保存成功后创建 delivery。Payload:
|
||||
收到邮件后按 邮箱 -> 域名 -> 全局 的顺序取第一个已配置的 Webhook(无配置则逐级回退),
|
||||
入队 delivery(冻结当时的 url/headers/key 配置)。Payload(docs/07):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -19,27 +20,37 @@ Webhook、API、MCP 全部属于 Console,Node 不实现这些能力。
|
||||
}
|
||||
```
|
||||
|
||||
Webhook 必须签名,建议提供 X-WmailHub-Event、X-WmailHub-Delivery、X-WmailHub-Timestamp、X-WmailHub-Signature。
|
||||
请求头:X-WmailHub-Event、X-WmailHub-Delivery、X-WmailHub-Timestamp、X-WmailHub-Signature
|
||||
(签名 = HMAC-SHA256(key, `${timestamp}.${body}`));配置了 key 时默认携带
|
||||
`Authorization: Bearer <key>`,自定义 Authorization 头优先;无 key 时不携带签名头。
|
||||
|
||||
2xx 为成功;5xx 和 timeout 重试;4xx 按策略处理。使用指数退避和最大尝试次数。
|
||||
2xx 为成功;5xx 和 timeout 按指数退避重试,达到最大尝试次数后置 exhausted。
|
||||
|
||||
## API
|
||||
|
||||
```text
|
||||
/api/v1/nodes
|
||||
/api/v1/accounts
|
||||
/api/v1/domains
|
||||
/api/v1/mailboxes
|
||||
/api/v1/emails
|
||||
/api/v1/webhooks
|
||||
/api/v1/mcp
|
||||
```
|
||||
|
||||
API 属于 Console。
|
||||
API 属于 Console,Bearer API Key(wmh_)认证。
|
||||
|
||||
## MCP
|
||||
|
||||
MCP 允许 Agent 查询邮箱、获取邮件、查询邮件状态、管理邮箱和 Webhook。Node 不暴露 MCP。
|
||||
MCP 允许 Agent 查询邮箱、获取邮件、创建/删除邮箱(list_mailboxes、list_emails、get_email、
|
||||
create_mailbox、delete_mailbox),Bearer MCP Key(wmh_)认证。
|
||||
|
||||
MCP/API 获取邮件时必须检查用户权限、邮件是否过期、mailbox scope 和 API credential scope。
|
||||
MCP/API 获取邮件时必须检查邮件是否过期、mailbox scope 和 API credential scope。
|
||||
|
||||
Webhook endpoint 必须防 SSRF,至少阻止 localhost、private IPv4/IPv6、link-local、metadata endpoint 和 DNS rebinding。
|
||||
## 内部 API
|
||||
|
||||
`/internal/email/authorize` 与 `/internal/email/ingest` 为 Email Worker 专用(docs/04),
|
||||
与 Webhook/API/MCP 无关。
|
||||
|
||||
## SSRF
|
||||
|
||||
Webhook endpoint 必须防 SSRF,至少阻止 localhost、private IPv4/IPv6、link-local、
|
||||
metadata endpoint 和 DNS rebinding。
|
||||
|
||||
Reference in New Issue
Block a user