wmailhub/docs/04_NODE_PROTOCOL.md

Email Worker <-> Console 内部协议(docs/11 §8,协议版本 1)

/internal/email/authorize 与 /internal/email/ingest 都是内部 API,不能匿名访问。 每个请求必须满足:HTTPS + 凭据 token + timestamp + nonce + body SHA256 + HMAC-SHA256。

身份 = 凭据 token(v2.10.0 起):Authorization 里放 worker_credentials.id(一账号一个, 部署 Worker 时烤进脚本),Console 按它精确定位凭据与所属账号。兼容:旧版 Worker 放的是 worker 脚本名——脚本名只在单个 Cloudflare 账号内唯一,多账号同名时 Console 会取全部同名 凭据逐一验签确定归属(v2.9.3 引入;只取一条会让先接入账号全部 401)。

请求头

Authorization: WmailHub-Worker <credential_token>
X-WmailHub-Timestamp: <unix_seconds>
X-WmailHub-Nonce: <random>
X-WmailHub-Body-SHA256: <hex>
X-WmailHub-Signature: <hex>
X-WmailHub-Protocol: 1

签名

body_hash  = SHA256(raw_body)
canonical  = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + body_hash
signature  = HMAC-SHA256(worker_credential_secret, canonical)

Console 必须校验

1. 凭据 token(存在且 credential active;旧脚本名按同名候选逐一验签);
2. timestamp(默认窗口 5 分钟);
3. nonce 不重复(唯一索引入库,主键冲突即 replay);
4. body hash;
5. HMAC;
6. credential 状态(撤销立即生效);
7. Worker 所属 Cloudflare 账号与收件域名一致。

API

POST /internal/email/authorize   { "recipient": "...", "sender": "...", "message_id": "..." }
POST /internal/email/ingest      raw MIME(message/rfc822),收件人经 X-WmailHub-Recipient/Sender 头传递

Console 收到 401/403 的 Worker 应视为凭据失效,不得无限重试。协议必须版本化。