BigCode
d4c1334143
- Console:React 19 + antd 6.6.5 前端(登录 admin/admin)+ Hono 管理 API (Nodes/Domains/Mailboxes/Emails/Webhooks/Keys/OAuth/Admin) - Node:Bun 转发节点(HMAC 签名、有限重试、心跳、结构化日志、优雅退出) - Email Worker:Cloudflare email handler + 本地联调入口 - shared:HMAC 协议(docs/04)、wmh_ Key(32 位)、AES-GCM 加密、SSRF 防护 - 邮件管线:postal-mime 解析、附件、catch-all、限额、malformed 降级、TTL 1 天 - Webhook:签名投递、指数退避重试、SSRF 校验、投递日志 - API v1 + MCP(JSON-RPC,六工具,凭据 kind 隔离) - Cloudflare OAuth:真实 + 本地 sim 模式,自动安装管线(幂等,无需手工命令) - 测试:bun test 41 例(协议安全/管线/TTL/Webhook/SSRF/MCP/OAuth/鉴权)+ Playwright UI 冒烟 - LOGO/favicon 由 codex CLI 生成
46 lines
1.1 KiB
Markdown
46 lines
1.1 KiB
Markdown
# Webhook、API 与 MCP
|
||
|
||
Webhook、API、MCP 全部属于 Console，Node 不实现这些能力。
|
||
|
||
## Webhook
|
||
|
||
邮件保存成功后创建 delivery。Payload：
|
||
|
||
```json
|
||
{
|
||
"event": "email.received",
|
||
"id": "msg_xxx",
|
||
"mailbox": "hello@example.com",
|
||
"from": "user@example.org",
|
||
"to": ["hello@example.com"],
|
||
"subject": "Hello",
|
||
"text": "Hello World",
|
||
"received_at": "2026-09-30T10:00:00Z"
|
||
}
|
||
```
|
||
|
||
Webhook 必须签名，建议提供 X-WmailHub-Event、X-WmailHub-Delivery、X-WmailHub-Timestamp、X-WmailHub-Signature。
|
||
|
||
2xx 为成功；5xx 和 timeout 重试；4xx 按策略处理。使用指数退避和最大尝试次数。
|
||
|
||
## API
|
||
|
||
```text
|
||
/api/v1/nodes
|
||
/api/v1/domains
|
||
/api/v1/mailboxes
|
||
/api/v1/emails
|
||
/api/v1/webhooks
|
||
/api/v1/mcp
|
||
```
|
||
|
||
API 属于 Console。
|
||
|
||
## MCP
|
||
|
||
MCP 允许 Agent 查询邮箱、获取邮件、查询邮件状态、管理邮箱和 Webhook。Node 不暴露 MCP。
|
||
|
||
MCP/API 获取邮件时必须检查用户权限、邮件是否过期、mailbox scope 和 API credential scope。
|
||
|
||
Webhook endpoint 必须防 SSRF，至少阻止 localhost、private IPv4/IPv6、link-local、metadata endpoint 和 DNS rebinding。
|