feat(auth): 接入邮箱验证与密码找回流程

2026-08-17 01:09:09 +08:00
parent c78b2f8ca5
commit 64aa3a4f07
13 changed files with 721 additions and 96 deletions
@@ -37,7 +37,7 @@
 ### 1.2 命名与格式

 - 请求与响应字段一律 **snake_case**（如 `cloud_id`、`page_size`、`received_like_count`）
- 日期时间一律为 **ISO 8601 字符串**（如 `2026-08-15T08:30:00.000Z`），可空的日期字段值为 `null`。唯一的例外见 2.3 第 6 条
+- 日期时间一律为 **ISO 8601 字符串**（如 `2026-08-15T08:30:00.000Z`），可空的日期字段值为 `null`。唯一的例外见 2.3 第 5 条
 - UUID 字段为标准 UUID 字符串

 ### 1.3 响应形态
@@ -91,7 +91,7 @@
 |---|---|---|
 | `id` | uuid | 用户 ID |
 | `name` | string | 用户名 |
-| `email` | string | 邮箱（注意 2.3 第 8 条的暴露范围问题） |
+| `email` | string | 邮箱（注意 2.3 第 7 条的暴露范围问题） |
 | `avatar_id` | uuid\|null | 头像 ID（当前恒为 `null`，头像功能未上线） |
 | `cloud_count` | int | 云图数（该用户上传的云图总数） |
 | `received_like_count` | int | 收到点赞数（名下云图获赞总和） |
@@ -110,7 +110,7 @@
 | `icon_id` | uuid\|null | 图标 ID |
 | `rarity` | int | 稀有度 |
 | `description` | string | 描述 |
-| `created_at` | string | 创建时间。⚠️ 列表与详情端点的格式不一致，见 2.3 第 6 条 |
+| `created_at` | string | 创建时间。⚠️ 列表与详情端点的格式不一致，见 2.3 第 5 条 |

 ### 1.6 上传约束（`POST /cloud`）

@@ -161,7 +161,7 @@
 | 304 | 图片 ETag 未变化，无响应 body | 继续使用本地缓存 |
 | 400 | 参数校验失败（形状②），或业务规则拒绝（形状①，如「新密码不能与当前密码相同」） | 检查参数；形状②可解析 `error.message` 定位字段 |
 | 401 | 未认证：未携带 token，或 token 无效/过期/已失效 | 清除本地登录态，跳转登录页 |
-| 403 | 已认证但无权限：角色不足、帐号被禁用、越权访问他人资源 | 按消息场景提示 |
+| 403 | 已认证但无权限：角色不足、邮箱未确认、帐号被禁用、越权访问他人资源 | 按消息场景提示 |
 | 404 | 资源不存在（形状①）；**也可能是纯文本**（见下方警告） | 区分 content-type 后处理 |
 | 405 | HTTP 方法不受端点支持 | 读取 `Allow` 响应头 |
 | 409 | 唯一性冲突：邮箱/用户名已被占用 | 提示用户更换 |
@@ -176,15 +176,13 @@
 以下是文档写作时核实的现状描述，**未来可能修复**。前端如需为之写防御代码，请做好移除准备。

 1. **两种错误形状并存**：400 校验错误不是业务错误信封（见 2.1）。
-2. **部分 404 是纯文本而非 JSON**，来源有三：(a) 未实现的占位端点（各章已标注）；(b) 以下端点的 `catch` 为空，数据库异常时返回纯文本 404 而非 500——`POST /auth/register`、`GET /profile/me`、`GET /admin/users`；(c) 未匹配任何路由的路径。
-3. **注册即禁用**：新注册用户的 `is_disabled` 默认为 `true`，而确认邮箱的端点（`/auth/confirm-email`）尚未实现。即**当前注册成功后无法登录**（登录返回 403「帐号已被禁用」），需后端在数据库手动启用。这是流程断点，前端联调注册流程时务必知悉。
-4. **静默续签只写 Cookie**：token 到期前的自动续签仅通过 `Set-Cookie` 下发新 token（见 3.4）。使用 Bearer header 模式的客户端**拿不到新 token**，30 分钟后必然 401，需重新登录。
-5. **`POST /admin/user` 是假端点**：它原样回显请求体（**含明文密码**），并不创建用户。
-6. **`GET /info/cloudtype`（列表）的 `created_at` 格式与其他端点不同**：是 PostgreSQL 原生字符串（如 `2026-08-15 08:30:00.123456+00`），而非 ISO 8601（`2026-08-15T08:30:00.000Z`）。详情端点 `/info/cloudtype/:id` 及其他所有端点均为 ISO 8601。前端解析该字段时需兼容两种格式。
-7. **用户名/邮箱长度不在 API 层校验**：数据库限制用户名 ≤ 16 字符、邮箱 ≤ 64 字符，但 zod 校验不拦截。超长注册会因 2.3.2(b) 返回**纯文本 404**；超长改名（`PATCH /profile/me`）返回 500。前端应自行限制输入长度。
-8. **`GET /profile/:user_id` 向任意登录用户暴露对方邮箱**：任何登录用户都能查到任意用户的 `email`。前端展示他人资料时不应展示邮箱，也不应假设该接口未来仍返回邮箱。
-9. **用户名唯一性的大小写规则不一致**：注册时的查重是大小写不敏感的（`Alice`/`alice` 视为重复），但数据库唯一约束与 `PATCH /profile/me` 改名是大小写敏感的（可改成仅大小写不同的名字）。
-10. **README 与代码的 CORS 环境变量不一致**：README 写的是 `CORS_ORIGINS`（复数、逗号分隔），代码实际读取 `CORS_ORIGIN`（单数、单个 origin）。本地联调配置后端环境变量时用单数。
+2. **部分 404 是纯文本而非 JSON**，来源有三：(a) 未实现的占位端点（各章已标注）；(b) `GET /profile/me` 与 `GET /admin/users` 的数据库异常会从空 `catch` 落到纯文本 404；(c) 未匹配任何路由的路径。注册与邮箱确认失败始终返回 JSON 信封。
+3. **静默续签只写 Cookie**：token 到期前的自动续签仅通过 `Set-Cookie` 下发新 token（见 3.4）。使用 Bearer header 模式的客户端**拿不到新 token**，30 分钟后必然 401，需重新登录。
+4. **`POST /admin/user` 是假端点**：它原样回显请求体（**含明文密码**），并不创建用户。
+5. **`GET /info/cloudtype`（列表）的 `created_at` 格式与其他端点不同**：是 PostgreSQL 原生字符串（如 `2026-08-15 08:30:00.123456+00`），而非 ISO 8601（`2026-08-15T08:30:00.000Z`）。详情端点 `/info/cloudtype/:id` 及其他所有端点均为 ISO 8601。前端解析该字段时需兼容两种格式。
+6. **用户名/邮箱长度不在 API 层校验**：数据库限制用户名 ≤ 16 字符、邮箱 ≤ 64 字符，但 zod 校验不拦截。超长注册与超长改名（`PATCH /profile/me`）会返回 JSON 500。前端应自行限制输入长度。
+7. **`GET /profile/:user_id` 向任意登录用户暴露对方邮箱**：任何登录用户都能查到任意用户的 `email`。前端展示他人资料时不应展示邮箱，也不应假设该接口未来仍返回邮箱。
+8. **用户名唯一性的大小写规则不一致**：注册时的查重是大小写不敏感的（`Alice`/`alice` 视为重复），但数据库唯一约束与 `PATCH /profile/me` 改名是大小写敏感的（可改成仅大小写不同的名字）。

 ---

@@ -203,7 +201,7 @@
 | 模式 | 适用 | 注意事项 |
 |---|---|---|
 | Cookie | 浏览器前端（推荐） | 登录后浏览器自动携带；`fetch` 需设 `credentials: "include"`；HttpOnly 使 JS 无法读取 token，天然防 XSS 窃取；可享受静默续签 |
-| Bearer | 非浏览器客户端（App、脚本） | 自行存储 `access_token` 并注入 header；**无法静默续签**（2.3 第 4 条），30 分钟后需重新登录 |
+| Bearer | 非浏览器客户端（App、脚本） | 自行存储 `access_token` 并注入 header；**无法静默续签**（2.3 第 3 条），30 分钟后需重新登录 |

 ### 3.3 CORS

@@ -218,14 +216,15 @@
 - **静默续签**：携带剩余有效期 ≤ 300 秒的 token 访问受保护端点时，服务端会在响应中**追加 `Set-Cookie` 写入新 token**。Cookie 模式下浏览器自动替换，前端无感知；Bearer 模式收不到新 token
 - 续签不适用的路径：`POST /auth/logout`、`PATCH /auth/password`
 - `/image` 请求只验证身份，不触发静默续签，避免一个页面的并发图片请求重复写 Cookie
- **立即失效**的三种情况：调用 `/auth/logout`、调用 `PATCH /auth/password` 改密、帐号被禁用。前两者会使该用户**所有已签发的 token 全部作废**（包括其他设备上的），并写入过期 Cookie
+- 认证中间件每次请求都会重新检查用户仍已确认邮箱且未被管理员禁用；任一条件不满足时，已有 JWT 也会被拒绝
+- **立即失效**的四种情况：调用 `/auth/logout`、调用 `PATCH /auth/password` 改密、通过 `/auth/reset-password` 重置密码、用户被禁用。前三者会使该用户**所有已签发的 token 全部作废**（包括其他设备上的）；密码修改与重置成功时还会写入过期 Cookie

 ### 3.5 认证相关错误消息对照

 | 状态码 | 消息原文 | 场景 |
 |---|---|---|
 | 401 | `未登录` | 受保护端点未携带任何 token |
-| 401 | `Token 无效或已过期` | token 签名无效、过期、已被吊销（登出/改密后）、或帐号已被禁用 |
+| 401 | `Token 无效或已过期` | token 签名无效、过期、已被吊销（登出、改密或密码重置后），或用户不再同时满足「邮箱已确认且未禁用」 |
 | 403 | `权限不足` | 已登录但角色不满足（如非 admin 访问 `/admin`） |

 注意「帐号被禁用」在**登录时**报 403「帐号已被禁用」，但已登录后被禁用，后续请求报的是 401「Token 无效或已过期」。
@@ -242,8 +241,8 @@

 | 参数 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|
-| `name` | string | 是 | ⚠️ 数据库限 ≤ 16 字符，API 层不校验（2.3 第 7 条） | 用户名，大小写不敏感查重 |
-| `email` | string | 是 | 合法邮箱格式；⚠️ 数据库限 ≤ 64 字符 | 邮箱，大小写不敏感查重 |
+| `name` | string | 是 | ⚠️ 数据库限 ≤ 16 字符，API 层不校验（2.3 第 6 条） | 用户名，大小写不敏感查重 |
+| `email` | string | 是 | 合法邮箱格式；⚠️ 数据库限 ≤ 64 字符 | 服务端去除首尾空白并转为小写后存储 |
 | `password` | string | 是 | 无强度校验 | 密码 |

 ```json
@@ -259,31 +258,89 @@
 ```json
 {
    "status_code": 201,
-    "message": "注册成功"
+    "message": "注册成功，请查收邮件并确认邮箱",
+    "email_sent": true
 }
 ```

+数据库提交成功但邮件暂时未发送时仍返回 `201`，`email_sent` 为 `false`，消息会提示稍后使用重发验证流程。用户、密码凭据和 24 小时有效的确认记录已经保留，不应重试注册。
+
 **错误**：

 | 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
 |---|---|---|---|
 | 400 | 参数校验失败 | zod 形状（2.1） | 检查字段 |
-| 409 | 邮箱已注册（大小写不敏感） | `该邮箱已被注册` | 提示换邮箱或直接登录 |
+| 409 | 已确认邮箱重复注册（大小写不敏感） | `该邮箱已被注册` | 提示直接登录 |
+| 409 | 未确认邮箱重复注册 | `该邮箱已被注册，请使用重发验证流程` | 引导至重发验证流程，不会覆盖原用户名或密码 |
 | 409 | 用户名已使用（大小写不敏感） | `该用户名已被使用` | 提示换用户名 |
-| 404 | ⚠️ 数据库异常（空 `catch`，2.3 第 2 条） | 纯文本 `404 Not Found` | 视为服务异常，稍后重试 |
+| 500 | 数据库、密码散列或服务端配置异常 | `注册失败` | 稍后重试；若此前已收到 201，不要重复注册 |

 **注意事项**：

- ⚠️ **注册成功后无法直接登录**：新用户默认 `is_disabled: true`，登录将返回 403（2.3 第 3 条）。联调时需后端手动启用帐号
- 注册响应**不返回 token、不写 Cookie**，登录需另行调用 `/auth/login`
+- 新用户的 `is_disabled` 为 `false`，`email_verified_at` 为空；两个状态相互独立。注册后必须先确认邮箱，再调用 `/auth/login`
+- 注册响应**不返回 token、不写 Cookie**
+- 确认邮件由 `Opencloud <opencloud@catpl.top>` 发出，同时包含 `https://cloud.catpl.top/verify-email?token=...` 链接和原始 token 备用文本。数据库仅保存使用 `JWT_SECRET` 生成的 HMAC 摘要

 ### 4.2 `POST /auth/resend-confirmation` — 重发确认邮件

-> ⚠️ **未实现**（占位端点）。请求体合法时当前返回纯文本 `404 Not Found`；请求体非法时仍会被 zod 校验拦截返回 400。请勿接入。
+- **认证**：无（公开）
+
+**请求体**（JSON）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `email` | string | 是 | 与注册、登录相同：服务端去除首尾空白并转为小写；不接受旧字段 `user_email` |
+
+```json
+{
+    "email": "watcher@example.com"
+}
+```
+
+**成功响应**：`200`
+
+```json
+{
+    "status_code": 200,
+    "message": "如果该邮箱符合条件，我们将发送验证邮件"
+}
+```
+
+未知邮箱、已确认邮箱、被管理员禁用、处于 60 秒冷却期、符合发送条件以及邮件供应商失败，都会收到完全相同的状态码和响应体。前端不能根据该响应判断邮件是否实际发送，也不应显示「邮箱存在」之类的提示。
+
+只有尚未确认、未被管理员禁用且不在冷却期内的用户会触发邮件发送。成功签发新 token 后，同一用户此前未消费的邮箱确认 token 全部失效；新 token 仍有 24 小时有效期，邮件内容与注册邮件相同。已消费记录会保留作为审计信息。
+
+重叠请求会按用户串行处理，至多签发一个可用 token。数据库签发或 Resend 失败不会改变上述公共响应。
+
+**错误**：请求体校验失败返回 `400` zod 形状（2.1）。

 ### 4.3 `POST /auth/confirm-email` — 确认邮箱

-> ⚠️ **未实现**（占位端点），行为同 4.2。该端点是解除「注册即禁用」（2.3 第 3 条）的设计入口，上线前注册流程是断的。
+- **认证**：无（公开）
+
+前端从确认链接读取 `token`，再提交：
+
+```json
+{
+    "token": "0123456789abcdef0123456789abcdef"
+}
+```
+
+**成功响应**：`200`
+
+```json
+{
+    "status_code": 200,
+    "message": "邮箱确认成功，请重新登录"
+}
+```
+
+确认会在一个数据库事务中消费未过期、未消费且用途为 `email_confirmation` 的记录，并写入用户的邮箱确认时间。它不会签发 JWT、不会写认证 Cookie，也绝不修改管理员禁用状态。
+
+| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
+|---|---|---|---|
+| 400 | token 未知、过期、已消费，或来自其他用途 | `确认链接无效或已过期` | 统一提示链接无效，并引导重发 |
+| 500 | 数据库或服务端配置异常 | `确认邮箱失败` | 稍后重试 |

 ### 4.4 `POST /auth/login` — 登录

@@ -293,7 +350,7 @@

 | 参数 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `email` | string | 是 | 邮箱，服务端按大小写不敏感匹配 |
+| `email` | string | 是 | 服务端去除首尾空白、转为小写后匹配 |
 | `password` | string | 是 | 密码 |

 ```json
@@ -317,7 +374,8 @@
 |---|---|---|---|
 | 400 | 参数校验失败 | zod 形状（2.1） | 检查字段 |
 | 401 | 邮箱不存在或密码错误（两者共用，防枚举） | `邮箱或密码错误` | 统一提示「邮箱或密码错误」 |
-| 403 | 帐号被禁用（含新注册未启用的帐号） | `帐号已被禁用` | 提示联系管理员 |
+| 403 | 帐号被管理员禁用 | `帐号已被禁用` | 提示联系管理员 |
+| 403 | 密码正确但邮箱尚未确认 | `邮箱尚未验证` | 引导至重发验证流程 |
 | 500 | 服务端异常 | `登录失败` | 稍后重试 |

 ### 4.5 `POST /auth/logout` — 登出
@@ -343,13 +401,75 @@

 **注意事项**：登出会使该用户**所有设备**的 token 立即失效（`tokenVersion` 递增），不只是当前会话。

-### 4.6 `POST /auth/forget-password` — 申请重置密码
+### 4.6 `POST /auth/forgot-password` — 申请重置密码

-> ⚠️ **未实现**（占位端点），行为同 4.2。请勿接入。
+- **认证**：无（公开）
+
+**请求体**（JSON）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `email` | string | 是 | 服务端去除首尾空白并转为小写；不接受旧字段 `user_email` |
+
+```json
+{
+    "email": "watcher@example.com"
+}
+```
+
+**成功响应**：`200`
+
+```json
+{
+    "status_code": 200,
+    "message": "如果该邮箱符合条件，我们将发送密码重置邮件"
+}
+```
+
+未知邮箱、邮箱未确认、被管理员禁用、处于 60 秒冷却期、符合发送条件以及邮件供应商失败，都会收到完全相同的状态码和响应体。只有邮箱已确认、未被禁用且不在冷却期内的用户会触发邮件发送。
+
+新签发的 `password_reset` token 有效期为 30 分钟，并使此前未消费的密码重置 token 失效；它与邮箱确认 token 用 purpose 隔离。邮件由 `Opencloud <opencloud@catpl.top>` 发出，链接到 `https://cloud.catpl.top/reset-password?email=...&token=...`。数据库和 Resend 失败不改变公共响应。
+
+**错误**：请求体校验失败返回 `400` zod 形状（2.1）。没有 `/auth/forget-password` 兼容路径。

 ### 4.7 `POST /auth/reset-password` — 重置密码

-> ⚠️ **未实现**（占位端点），行为同 4.2。请勿接入。
+- **认证**：无（公开）
+
+**请求体**（JSON）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `email` | string | 是 | 邮件链接中的邮箱；服务端再次规范化 |
+| `token` | string | 是 | 邮件链接中的原始 token |
+| `new_password` | string | 是 | 新密码；不能与当前密码相同，不额外扩大密码策略 |
+
+```json
+{
+    "email": "watcher@example.com",
+    "token": "0123456789abcdef0123456789abcdef",
+    "new_password": "new-s3cret-password"
+}
+```
+
+**成功响应**：`200`，同时写入过期认证 Cookie
+
+```json
+{
+    "status_code": 200,
+    "message": "密码重置成功，请使用新密码重新登录"
+}
+```
+
+成功时，服务端在同一数据库事务中消费 token、更新密码哈希和凭据更新时间，并递增 `tokenVersion`。此前在所有设备签发的 JWT 随即失效；响应不会签发新 JWT，用户必须重新登录。
+
+token 必须同时匹配规范化邮箱、HMAC 摘要、`password_reset` purpose、有效期、未消费状态和目标用户；用户在消费时仍须邮箱已确认且未被管理员禁用。重置不会修改邮箱确认时间或管理员禁用状态。
+
+| 状态码 | 触发条件 | 消息原文 | 前端建议动作 |
+|---|---|---|---|
+| 400 | token 未知、过期、已消费、已被替换、用途错误、邮箱不匹配，或用户不再符合状态要求 | `重置链接无效或已过期` | 统一提示链接无效，重新申请 |
+| 400 | 新密码与当前密码相同 | `新密码不能与当前密码相同` | 要求输入不同密码 |
+| 500 | 数据库或服务端配置异常 | `重置密码失败` | 稍后重试 |

 ### 4.8 `PATCH /auth/password` — 修改密码

@@ -847,7 +967,7 @@
 | 404 | 用户不存在 | `该用户不存在` | 提示用户不存在 |
 | 500 | 服务端异常 | `服务器发生内部错误` | 稍后重试 |

-**注意事项**：⚠️ 响应包含对方 `email`（2.3 第 8 条）。展示他人资料页时不应展示邮箱字段。
+**注意事项**：⚠️ 响应包含对方 `email`（2.3 第 7 条）。展示他人资料页时不应展示邮箱字段。

 ### 6.6 `GET /profile/:user_id/likes` — 查看用户点赞记录

@@ -905,7 +1025,7 @@
 ]
 ```

-**注意事项**：⚠️ 本端点的 `created_at` 是 PostgreSQL 原生格式（上例），**不是** ISO 8601（2.3 第 6 条），解析时自行兼容。
+**注意事项**：⚠️ 本端点的 `created_at` 是 PostgreSQL 原生格式（上例），**不是** ISO 8601（2.3 第 5 条），解析时自行兼容。

 **错误**：500 `服务器发生内部错误`。

@@ -955,7 +1075,7 @@

 ### 8.4 `POST /admin/user` — 创建用户

-> ⚠️ **假端点**（2.3 第 5 条）：通过 zod 校验后**原样回显请求体（含明文密码）**，不创建任何用户。响应为 `200 { name, email, password, role }`。请勿接入，更不要在任何持久化日志中记录其响应。
+> ⚠️ **假端点**（2.3 第 4 条）：通过 zod 校验后**原样回显请求体（含明文密码）**，不创建任何用户。响应为 `200 { name, email, password, role }`。请勿接入，更不要在任何持久化日志中记录其响应。

 ### 8.5 `GET /admin/clouds` — 全状态云图列表