把 2FA 管理器放到 Cloudflare Workers 上

2FACloudflare WorkersD1Security

项目背景

2Fauth-Cloudflare 是我最近重点维护的项目。想法很直接：把双因素认证条目放到 Cloudflare Workers + D1 这套边缘环境里管理，Web、Android、浏览器扩展都走同一套 API，不依赖自己的服务器。

目前包含 Web 登录、TOTP/HOTP 条目、分组、用户角色、导入导出、加密备份，以及面向客户端的 /api/v1 Bearer Token API。

核心取舍

安全相关的实现我放在优先级最高的位置，没有商量：

  • OTP secret 用 AES-GCM 加密后再写入 D1。
  • Web 登录走 HttpOnly session cookie。
  • API 客户端走 access token + refresh token。
  • 登录侧加入风险控制，预留 Cloudflare Turnstile。
  • 浏览器扩展的 CORS 用精确 origin 白名单，不做通配。
  • 明文导出要谨慎，默认推荐加密备份。

这些设计确实让开发复杂了一些，但 2FA 管理器本来就不是那种“能跑就行”的项目。

为什么需要 API v1

一开始 Web UI 能解决基本使用问题。但要做 Android 客户端和浏览器扩展，继续依赖网页就说不通了。稳定的 /api/v1 让不同客户端只处理自己的体验，认证、权限、条目和验证码生成逻辑全留在 Worker 里。

目前常用的接口：

  • POST /api/v1/auth/login
  • POST /api/v1/auth/refresh
  • GET /api/v1/entries
  • POST /api/v1/codes/batch
  • POST /api/v1/entries/:id/hotp

先把服务端契约稳住，移动端和扩展端迭代起来就顺多了。

自动化部署

项目接了 GitHub Actions，构建、D1 迁移、部署全部自动化。Cloudflare Workers 项目如果靠手动记步骤，早晚出错——配置、迁移版本、代码版本一多就容易对不上。

现在我的习惯是把部署流程写进仓库，不放在自己笔记里。换设备或过一段时间回来维护，打开仓库就能恢复上下文。