docs: add auth captcha implementation plan

Made-with: Cursor
10 hours ago · 9ae8e46777
1 changed files with 609 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-19-auth-captcha.md
+++ b/docs/superpowers/plans/2026-04-19-auth-captcha.md
@ -0,0 +1,609 @@
+# Auth Captcha Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为 `POST /api/auth/login` 与 `POST /api/auth/register` 增加自建 SVG 图形验证码与基于内存的 IP 限流；新增 `GET /api/auth/captcha`；登录/注册页展示验证码与换一张。
+
+**Architecture:** 使用 `svg-captcha` 生成 SVG 与答案，答案经规范化后存入进程内 `Map`（TTL 默认 3 分钟，校验成功或失败均删除 challenge）。限流复用现有 `assertUnderRateLimit`（`server/utils/simple-rate-limit.ts`）。客户端 IP 统一使用 `getRequestIP(event, { xForwardedFor: true }) ?? "unknown"`，与评论、管理接口一致。
+
+**Tech Stack:** Nuxt 4 / Nitro、h3、`svg-captcha`、Bun `bun:test`、现有 `R.success` / `defineWrappedResponseHandler`。
+
+**规格依据:** [2026-04-19-auth-captcha-design.md](../specs/2026-04-19-auth-captcha-design.md)
+
+---
+
+## File Structure Map
+
+| 路径 | 动作 | 职责 |
+|------|------|------|
+| `package.json` | Modify | 增加依赖 `svg-captcha` |
+| `server/service/captcha/store.ts` | Create | 内存 challenge 存储、`captchaCreate`、`captchaConsume` |
+| `server/service/captcha/store.test.ts` | Create | store 单元测试 |
+| `server/service/captcha/challenge.ts` | Create | 封装 `svg-captcha` + 调用 `captchaCreate`，导出 `createCaptchaChallenge()` |
+| `server/service/captcha/challenge.test.ts` | Create | 可选：对 `createCaptchaChallenge` 做轻量断言（含 `captchaId` 与非空 `imageSvg`） |
+| `server/service/captcha/validate-body.ts` | Create | `assertLoginRegisterCaptchaFieldsPresent`（缺少字段时 400） |
+| `server/api/auth/captcha.get.ts` | Create | 签发验证码 JSON + `Cache-Control: no-store` + 限流 |
+| `server/api/auth/login.post.ts` | Modify | 限流 → 读 body → 校验字段 → `captchaConsume` → `loginUser` |
+| `server/api/auth/register.post.ts` | Modify | 限流 → 读 body → 校验字段 → `captchaConsume` → `allowRegister` → `registerUser` |
+| `server/utils/auth-api-routes.ts` | Modify | allowlist 增加 `GET /api/auth/captcha` |
+| `app/pages/login/index.vue` | Modify | 拉取/刷新验证码、表单项、`img` data URL |
+| `app/pages/register/index.vue` | Modify | 同上 |
+
+---
+
+### Task 1: 添加依赖 `svg-captcha`
+
+**Files:**
+
+- Modify: `package.json`（`dependencies`）
+
+- [ ] **Step 1: 安装依赖**
+
+在项目根目录执行：
+
+```bash
+bun add svg-captcha
+```
+
+预期：`package.json` 出现 `"svg-captcha"` 条目且无安装错误。
+
+- [ ] **Step 2: 确认类型**
+
+运行：
+
+```bash
+bunx tsc --noEmit -p server 2>/dev/null || npx nuxt prepare
+```
+
+若 Nuxt 工程无独立 `server` tsconfig，可仅运行 `bun run postinstall`（即 `nuxt prepare`）。预期：无与 `svg-captcha` 导入相关的报错（该包自带类型声明）。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add package.json bun.lock
+git commit -m "chore: add svg-captcha for auth captcha"
+```
+
+---
+
+### Task 2: 实现验证码内存存储与单元测试
+
+**Files:**
+
+- Create: `server/service/captcha/store.ts`
+- Create: `server/service/captcha/store.test.ts`
+
+- [ ] **Step 1: 编写会失败的测试（行为约定）**
+
+创建 `server/service/captcha/store.test.ts`：
+
+```typescript
+import { describe, expect, test } from "bun:test";
+import { captchaConsume, captchaCreate } from "./store";
+
+describe("captcha store", () => {
+  test("consume succeeds once then fails", () => {
+    const { captchaId } = captchaCreate("ab12");
+    expect(captchaConsume(captchaId, "ab12")).toBe(true);
+    expect(captchaConsume(captchaId, "ab12")).toBe(false);
+  });
+
+  test("wrong answer invalidates challenge", () => {
+    const { captchaId } = captchaCreate("ab12");
+    expect(captchaConsume(captchaId, "xxxx")).toBe(false);
+    expect(captchaConsume(captchaId, "ab12")).toBe(false);
+  });
+
+  test("trim + lowercase on user input", () => {
+    const { captchaId } = captchaCreate("ab12");
+    expect(captchaConsume(captchaId, "  AB12  ")).toBe(true);
+  });
+
+  test("length mismatch fails without throwing", () => {
+    const { captchaId } = captchaCreate("ab12");
+    expect(captchaConsume(captchaId, "x")).toBe(false);
+  });
+
+  test("expired challenge fails", () => {
+    const { captchaId } = captchaCreate("ab12", { ttlMs: -1000 });
+    expect(captchaConsume(captchaId, "ab12")).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+```bash
+bun test server/service/captcha/store.test.ts
+```
+
+预期：导入/函数未定义类失败。
+
+- [ ] **Step 3: 实现 `store.ts`**
+
+创建 `server/service/captcha/store.ts`：
+
+```typescript
+import { randomUUID } from "node:crypto";
+import { timingSafeEqual } from "node:crypto";
+
+const DEFAULT_TTL_MS = 180_000;
+
+type Entry = { answerBuf: Buffer; expiresAt: number };
+
+const store = new Map<string, Entry>();
+
+function sweepExpired(now: number) {
+  for (const [id, e] of store) {
+    if (now > e.expiresAt) {
+      store.delete(id);
+    }
+  }
+}
+
+/** `answerNormalized` 必须已是规范形式（小写、无首尾空格），与 svg-captcha 生成结果一致 */
+export function captchaCreate(
+  answerNormalized: string,
+  options?: { ttlMs?: number },
+): { captchaId: string } {
+  const now = Date.now();
+  sweepExpired(now);
+  const ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+  const captchaId = randomUUID();
+  store.set(captchaId, {
+    answerBuf: Buffer.from(answerNormalized, "utf8"),
+    expiresAt: now + ttlMs,
+  });
+  return { captchaId };
+}
+
+/** 成功或失败均删除 challenge（含答案错误、过期），与规格一致 */
+export function captchaConsume(captchaId: unknown, rawAnswer: unknown): boolean {
+  if (typeof captchaId !== "string" || typeof rawAnswer !== "string") {
+    return false;
+  }
+  const now = Date.now();
+  sweepExpired(now);
+  const entry = store.get(captchaId);
+  if (!entry || now > entry.expiresAt) {
+    if (entry) {
+      store.delete(captchaId);
+    }
+    return false;
+  }
+  const guessBuf = Buffer.from(rawAnswer.trim().toLowerCase(), "utf8");
+  if (guessBuf.length !== entry.answerBuf.length) {
+    store.delete(captchaId);
+    return false;
+  }
+  const ok = timingSafeEqual(guessBuf, entry.answerBuf);
+  store.delete(captchaId);
+  return ok;
+}
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+```bash
+bun test server/service/captcha/store.test.ts
+```
+
+预期：全部 PASS。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add server/service/captcha/store.ts server/service/captcha/store.test.ts
+git commit -m "feat(auth): in-memory captcha store with tests"
+```
+
+---
+
+### Task 3: 封装 `createCaptchaChallenge`
+
+**Files:**
+
+- Create: `server/service/captcha/challenge.ts`
+- Create: `server/service/captcha/challenge.test.ts`
+
+- [ ] **Step 1: 编写测试**
+
+创建 `server/service/captcha/challenge.test.ts`（不解析 SVG 文本，避免随 `svg-captcha` 版本脆断；答案消费路径由 `store.test.ts` 覆盖）：
+
+```typescript
+import { describe, expect, test } from "bun:test";
+import { createCaptchaChallenge } from "./challenge";
+
+describe("createCaptchaChallenge", () => {
+  test("returns captchaId and non-empty svg", () => {
+    const { captchaId, imageSvg } = createCaptchaChallenge();
+    expect(captchaId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+    expect(imageSvg.length).toBeGreaterThan(50);
+    expect(imageSvg.includes("svg")).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+```bash
+bun test server/service/captcha/challenge.test.ts
+```
+
+预期：导入失败。
+
+- [ ] **Step 3: 实现 `challenge.ts`**
+
+创建 `server/service/captcha/challenge.ts`：
+
+```typescript
+import svgCaptcha from "svg-captcha";
+import { captchaCreate } from "./store";
+
+/** 与规格一致：易混淆字符已剔除，长度 5 */
+const CHAR_PRESET = "abcdefghjkmnpqrstuvwxyz23456789";
+
+export function createCaptchaChallenge(): { captchaId: string; imageSvg: string } {
+  const { data: imageSvg, text } = svgCaptcha.create({
+    size: 5,
+    noise: 2,
+    color: true,
+    charPreset: CHAR_PRESET,
+    background: "#f4f4f5",
+  });
+  const answerNormalized = text.toLowerCase();
+  const { captchaId } = captchaCreate(answerNormalized);
+  return { captchaId, imageSvg };
+}
+```
+
+- [ ] **Step 4: 运行测试**
+
+```bash
+bun test server/service/captcha/challenge.test.ts
+```
+
+预期：PASS。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add server/service/captcha/challenge.ts server/service/captcha/challenge.test.ts
+git commit -m "feat(auth): svg captcha challenge factory"
+```
+
+---
+
+### Task 4: 请求体验证辅助函数
+
+**Files:**
+
+- Create: `server/service/captcha/validate-body.ts`
+
+- [ ] **Step 1: 实现**
+
+创建 `server/service/captcha/validate-body.ts`：
+
+```typescript
+export type AuthCredentialsAndCaptcha = {
+  username: string;
+  password: string;
+  captchaId: string;
+  captchaAnswer: string;
+};
+
+export function assertLoginRegisterCaptchaFieldsPresent(
+  body: unknown,
+): asserts body is AuthCredentialsAndCaptcha {
+  if (typeof body !== "object" || body === null) {
+    throw createError({ statusCode: 400, statusMessage: "无效请求" });
+  }
+  const b = body as Record<string, unknown>;
+  if (typeof b.username !== "string" || typeof b.password !== "string") {
+    throw createError({ statusCode: 400, statusMessage: "无效请求" });
+  }
+  if (typeof b.captchaId !== "string" || b.captchaId.trim() === "") {
+    throw createError({ statusCode: 400, statusMessage: "请完成验证码" });
+  }
+  if (typeof b.captchaAnswer !== "string" || b.captchaAnswer.trim() === "") {
+    throw createError({ statusCode: 400, statusMessage: "请完成验证码" });
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add server/service/captcha/validate-body.ts
+git commit -m "feat(auth): validate captcha fields on login/register body"
+```
+
+---
+
+### Task 5: `GET /api/auth/captcha`
+
+**Files:**
+
+- Create: `server/api/auth/captcha.get.ts`
+- Modify: `server/utils/auth-api-routes.ts`
+
+- [ ] **Step 1: 实现 handler**
+
+创建 `server/api/auth/captcha.get.ts`：
+
+```typescript
+import { getRequestIP } from "h3";
+import { createCaptchaChallenge } from "#server/service/captcha/challenge";
+import { assertUnderRateLimit } from "#server/utils/simple-rate-limit";
+
+export default defineWrappedResponseHandler(async (event) => {
+  setResponseHeader(event, "cache-control", "no-store");
+  const ip = getRequestIP(event, { xForwardedFor: true }) ?? "unknown";
+  assertUnderRateLimit(`auth-captcha:${ip}`, 60, 60_000);
+
+  const { captchaId, imageSvg } = createCaptchaChallenge();
+  return R.success({ captchaId, imageSvg });
+});
+```
+
+- [ ] **Step 2: 更新 allowlist**
+
+在 `server/utils/auth-api-routes.ts` 的 `API_ALLOWLIST` 中增加一行（保持字母顺序可选）：
+
+```typescript
+{ path: "/api/auth/captcha", methods: ["GET"] },
+```
+
+- [ ] **Step 3: 手工验证（开发服务器）**
+
+运行 `bun run dev`，请求：
+
+```bash
+curl -sI "http://localhost:3000/api/auth/captcha" | tr -d '\r' | grep -i cache-control
+```
+
+预期：响应头含 `cache-control: no-store`（大小写不敏感）。再：
+
+```bash
+curl -s "http://localhost:3000/api/auth/captcha"
+```
+
+预期：JSON 含 `captchaId` 与 `imageSvg`，且最外层为项目统一的 `R.success` 包装结构（与现有 API 一致）。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add server/api/auth/captcha.get.ts server/utils/auth-api-routes.ts
+git commit -m "feat(auth): GET /api/auth/captcha endpoint"
+```
+
+---
+
+### Task 6: 登录与注册 API 接入验证码
+
+**Files:**
+
+- Modify: `server/api/auth/login.post.ts`
+- Modify: `server/api/auth/register.post.ts`
+
+- [ ] **Step 1: 修改 `login.post.ts` 完整替换为**
+
+```typescript
+import { getRequestIP } from "h3";
+import { loginUser } from "#server/service/auth";
+import { toPublicAuthError } from "#server/service/auth/errors";
+import { setSessionCookie } from "#server/service/auth/cookie";
+import { captchaConsume } from "#server/service/captcha/store";
+import { assertLoginRegisterCaptchaFieldsPresent } from "#server/service/captcha/validate-body";
+import { assertUnderRateLimit } from "#server/utils/simple-rate-limit";
+
+export default defineWrappedResponseHandler(async (event) => {
+  const ip = getRequestIP(event, { xForwardedFor: true }) ?? "unknown";
+  assertUnderRateLimit(`auth-login:${ip}`, 30, 60_000);
+
+  const body = await readBody(event);
+  assertLoginRegisterCaptchaFieldsPresent(body);
+  if (!captchaConsume(body.captchaId, body.captchaAnswer)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "验证码错误或已过期，请重试",
+    });
+  }
+
+  try {
+    const result = await loginUser({
+      username: body.username,
+      password: body.password,
+    });
+    setSessionCookie(event, result.sessionId);
+    return R.success({
+      user: result.user,
+    });
+  } catch (err) {
+    throw toPublicAuthError(err);
+  }
+});
+```
+
+- [ ] **Step 2: 修改 `register.post.ts` 完整替换为**
+
+```typescript
+import { getRequestIP } from "h3";
+import { registerUser } from "#server/service/auth";
+import { toPublicAuthError } from "#server/service/auth/errors";
+import { captchaConsume } from "#server/service/captcha/store";
+import { assertLoginRegisterCaptchaFieldsPresent } from "#server/service/captcha/validate-body";
+import { assertUnderRateLimit } from "#server/utils/simple-rate-limit";
+
+export default defineWrappedResponseHandler(async (event) => {
+  const ip = getRequestIP(event, { xForwardedFor: true }) ?? "unknown";
+  assertUnderRateLimit(`auth-register:${ip}`, 20, 60_000);
+
+  const body = await readBody(event);
+  assertLoginRegisterCaptchaFieldsPresent(body);
+  if (!captchaConsume(body.captchaId, body.captchaAnswer)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "验证码错误或已过期，请重试",
+    });
+  }
+
+  const allowRegister = await event.context.config.getGlobal("allowRegister");
+  if (!allowRegister) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "当前已关闭注册",
+    });
+  }
+
+  try {
+    const user = await registerUser({
+      username: body.username,
+      password: body.password,
+    });
+    return R.success({
+      user,
+    });
+  } catch (err) {
+    throw toPublicAuthError(err);
+  }
+});
+```
+
+- [ ] **Step 3: 运行单元测试回归**
+
+```bash
+bun test server/service/auth/index.test.ts server/service/captcha/
+```
+
+预期：全部 PASS（auth 测试不经过 HTTP，行为不变）。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add server/api/auth/login.post.ts server/api/auth/register.post.ts
+git commit -m "feat(auth): require captcha on login and register"
+```
+
+---
+
+### Task 7: 前端登录与注册页
+
+**Files:**
+
+- Modify: `app/pages/login/index.vue`
+- Modify: `app/pages/register/index.vue`
+
+- [ ] **Step 1: 登录页 — script 增量**
+
+在 `LoginFormState` 中增加 `captchaAnswer: string`；增加 `captchaIdRef`、`captchaImageSrc` 两个 `ref('')`；增加方法：
+
+```typescript
+const captchaIdRef = ref('')
+const captchaImageSrc = ref('')
+
+async function refreshCaptcha() {
+  state.captchaAnswer = ''
+  captchaImageSrc.value = ''
+  const res = await fetchData<{ captchaId: string; imageSvg: string }>('/api/auth/captcha', {
+    method: 'GET',
+    notify: false,
+  })
+  captchaIdRef.value = res.captchaId
+  captchaImageSrc.value = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(res.imageSvg)}`
+}
+
+onMounted(() => {
+  void refreshCaptcha()
+})
+```
+
+说明：`app/composables/useClientApi.ts` 中 `fetchData` 已对 `R.success` 做 `unwrapApiBody`，故 `res` 即为 `{ captchaId, imageSvg }`（与现有 `/api/auth/login` 用法一致）。
+
+在 `onSubmit` 的 `body` 中增加：
+
+```typescript
+captchaId: captchaIdRef.value,
+captchaAnswer: state.captchaAnswer,
+```
+
+在 `catch` 与成功跳转前的失败路径：调用 `await refreshCaptcha()`（成功登录无需刷新）。建议在 `catch` 内与 `finally` 中根据是否报错刷新：至少在 `catch` 末尾 `void refreshCaptcha()`。
+
+在 `validate` 中为 `captchaAnswer` 增加非空校验。
+
+- [ ] **Step 2: 登录页 — template**
+
+在密码字段与提交按钮之间增加：
+
+```vue
+<UFormField label="验证码" name="captchaAnswer" required>
+  <div class="flex gap-2 items-center">
+    <img
+      v-if="captchaImageSrc"
+      :src="captchaImageSrc"
+      alt="验证码"
+      class="h-10 rounded border border-default bg-elevated"
+    />
+    <UInput
+      v-model="state.captchaAnswer"
+      placeholder="请输入图中字符"
+      class="flex-1 min-w-0"
+      autocomplete="off"
+    />
+    <UButton type="button" color="neutral" variant="outline" @click="refreshCaptcha">
+      换一张
+    </UButton>
+  </div>
+</UFormField>
+```
+
+- [ ] **Step 3: 注册页**
+
+对 `register/index.vue` 做与登录页对称的修改（同一 `refreshCaptcha` 逻辑、`captchaIdRef`、`onMounted`、`onSubmit` body、`catch` 刷新、`validate`）。
+
+- [ ] **Step 4: 手工验收**
+
+启动 `bun run dev`：打开 `/login`、`/register`，确认验证码显示、换一张、错误验证码提示、正确验证码后登录/注册仍可用。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/pages/login/index.vue app/pages/register/index.vue
+git commit -m "feat(auth): captcha UI on login and register pages"
+```
+
+---
+
+## Plan Self-Review
+
+**1. Spec coverage**
+
+| 规格章节 | 对应 Task |
+|----------|-----------|
+| 内存 challenge、TTL、一次性消费 | Task 2 |
+| SVG 图形、`imageSvg` + data URL | Task 3、7 |
+| `GET /api/auth/captcha`、`no-store`、限流 | Task 5 |
+| 登录/注册 body 字段与顺序（先限流再验证码再业务） | Task 6 |
+| 注册关闭时先验证码再 403 | Task 6 `register.post.ts` |
+| allowlist | Task 5 |
+| 错误码 400/429/403 文案 | Task 4–6 |
+| IP 策略 | 全文使用 `getRequestIP` 与现有限流工具 |
+
+**2. Placeholder scan**
+
+无 TBD/TODO；限流数字为明确常量，可在实现时抽到单文件但非必须。
+
+**3. Type consistency**
+
+`AuthCredentialsAndCaptcha`、`readBody` 与 `loginUser`/`registerUser` 入参字段一致；验证码字段名全程 `captchaId` / `captchaAnswer`。
+
+---
+
+**Plan complete and saved to `docs/superpowers/plans/2026-04-19-auth-captcha.md`. Two execution options:**
+
+1. **Subagent-Driven（推荐）** — 每个 Task 派生子代理并在 Task 之间做简短审查，迭代快。  
+2. **Inline Execution** — 在本会话中按 Task 顺序实现，在关键 Task（如 Task 6–7）后人工检查点。
+
+你更倾向哪一种？