email-helper

把 Resend 发件域名注册与 DNS 验证记录配置，从业务项目里彻底分离出去。

功能 · 责任边界 · 安装 · 快速开始 · 命令 · 工作原理 · 文档

email-helper 是一个低频基础设施 CLI：读取 Resend 要求的 DNS 记录，与你的 authoritative DNS zone 对账，只补齐缺失的记录，然后触发域名验证。它默认只生成 计划——没有 --apply，进程不会对远程产生任何写入。

[!IMPORTANT] 本工具不发送邮件、不生成验证码、不管理模板，也不会创建业务项目使用的 Resend sending key。它只创建记录，从不替换或删除任何 DNS 记录。

功能

• 默认 dry-run —— 先输出完整计划；写入需要显式 --apply，非交互写入还要 --yes --non-interactive 三个门禁同时满足。
• 语义对账 —— 以 Resend 返回的记录作为期望状态的唯一来源，按 owner/type/data 语义指纹比对；TTL 差异不触发写入，DKIM 记录的 owner 与数量从不硬编码。
• 冲突前置拦截 —— duplicate、CNAME/MX/SPF 冲突或不支持的记录类型，会在任何 一条 DNS 写入之前终止整组操作。
• 可安全重跑 —— 每步落 receipt，但重跑始终以远程事实为准；中断后原样重跑不会 产生重复记录。
• 凭据不过 shell —— 只从权限受控文件或关闭回显的 TTY 读取，输出统一脱敏， receipt 里不含任何 secret。
• provider 可扩展 —— DNS provider 通过显式 registry 解析，核心对账逻辑里没有 任何 GoDaddy 分支。当前内置 GoDaddy。
• 零运行时依赖 —— Node.js 原生 ESM 与内置 API，无构建步骤。

责任边界

| 能力 | email-helper | 业务邮件服务 | server-helper | |---|---:|---:|---:| | 注册 Resend 发件域名 | 是 | 否 | 否 | | 对账并创建缺失 DNS 验证记录 | 是 | 否 | 否 | | 触发并查询域名验证 | 是 | 否 | 否 | | 发送邮件、验证码、模板、限流 | 否 | 是 | 否 | | 主机、Nginx、TLS、站点 | 否 | 否 | 是 |

环境要求

• Node.js 22 或更高版本，macOS 或 Linux
• Resend full_access bootstrap key
• 具有 domains.domain:read 与 domains.dns:update scope 的 GoDaddy PAT
• 发件域名对应的 GoDaddy authoritative DNS zone 访问权限

安装

npm install --global @xenonbyte/email-helper
email-helper --version

[!NOTE] 包尚未发布到 npm registry。发布前可从仓库根目录直接运行 node bin/email-helper.js， 或用 npm pack 产出的 tarball 本地安装。

快速开始

1. 准备权限受控的凭据文件

mkdir -m 700 ~/.config/email-helper
$EDITOR ~/.config/email-helper/bootstrap.env
chmod 600 ~/.config/email-helper/bootstrap.env

文件采用严格的 KEY=value 格式，允许空行与 # 注释，未知键会被拒绝：

RESEND_API_KEY=<full-access-bootstrap-key>
GODADDY_PAT=<personal-access-token>

2. 跑一次完全离线的本地检查

email-helper doctor --offline \
  --resend-credentials-file ~/.config/email-helper/bootstrap.env \
  --dns-credentials-file ~/.config/email-helper/bootstrap.env

3. 生成只读计划

email-helper domain configure \
  --domain mail.example.com \
  --dns-zone example.com \
  --region us-east-1 \
  --resend-credentials-file ~/.config/email-helper/bootstrap.env \
  --dns-credentials-file ~/.config/email-helper/bootstrap.env

4. 确认计划后执行

在同一条命令末尾加上 --apply。交互模式下会分阶段要求精确确认，确认之后远程若发生 漂移会带着修订计划重新确认；非交互模式下只接受仍属于已批准子集的写入，否则 fail closed。

[!WARNING] 自动化环境必须同时提供 --apply --yes --non-interactive，缺任一项都会被拒绝。 --yes 只预批准计划，不会放宽任何安全检查。

命令

| 命令 | 说明 | |---|---| | email-helper domain configure | 唯一允许远程写入的命令，默认 dry-run | | email-helper domain status | 严格只读，检查远程是否已完全一致 | | email-helper doctor | 本地状态、凭据文件与远程可达性诊断 | | email-helper doctor --offline | 禁网络、禁提示、不读取任何 secret 值 |

[!TIP] 任何命令加 --format json，stdout 就只输出一个 schema v1 对象，便于脚本消费； 加 --verbose 会把安全诊断写到 stderr，不污染结果。

DNS 尚未传播时保留 receipt，稍后原样重跑 apply 即可继续。精确参数、默认值、JSON 字段与退出码以 CLI 参考 为准。

工作原理

planned → resend_domain_created → dns_configuring → dns_configured
        → verification_triggered → verification_pending | completed

• Resend 返回的记录经规范化成为 canonical record；GoDaddy zone 快照连续读两次一致 后才作为实际状态，两边只按语义指纹比对。
• 每次远程写入前取单写锁，写入后原子更新 receipt。receipt 只表示「最近一次持久完成 的阶段」，不是成功证明。
• 不确定的写入（超时、5xx）一律先回读远程事实并采纳结果，绝不盲目重发，也不用删除 远程资源的方式回滚。

细节见架构与安全模型。

文档

| 文档 | 内容 | |---|---| | 使用指南 | 从零到 verified 的完整操作流程 | | CLI 参考 | 参数、默认值、JSON schema、退出码 | | 架构 | 组件边界、数据流、状态机、重试模型 | | 安全模型 | 凭据职责、文件检查、脱敏与威胁边界 | | Resend 契约 | 依赖的 Resend 行为与字段 | | GoDaddy provider | 分页、映射、错误分类 | | 开发新 provider | provider contract 与实施清单 | | 故障排查 | 常见失败与恢复方式 | | 发布流程 | 版本同步、质量门、回滚 |