邮件验证流程设计与限流策略

Tue, 09 Jul 2024 00:00:00 +0000

注册后发验证邮件看似简单，但 token 过期、重发限制、验证状态管理这些细节才是关键。

整体流程

用户注册成功 → 自动发送验证邮件
邮件包含验证链接：/verify-email?token=xxx
用户点击链接 → 验证 token → 更新 emailVerified 字段
未验证时可以重发邮件（有限流）

KV 存储过期 Token

验证 token 存储在 Cloudflare KV 中，利用 KV 的 expirationTtl 自动过期：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// src/utils/kv-token.ts

export async function createExpiringToken({
 key,
 expiresInSeconds,
 payload,
 createToken = createId,
}: CreateExpiringTokenParams): Promise<string> {
 const kv = await getTokenKV();
 const token = createToken();
 const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);

 await kv.put(
 key(token),
 JSON.stringify({
 ...payload,
 expiresAt: expiresAt.toISOString(),
 }),
 {
 expirationTtl: expiresInSeconds, // KV 自动过期，无需手动清理
 }
 );

 return token;
}

Token 的核心设计：

用 cuid2 生成随机 token，不可预测
存储在 KV 中，key 格式为 verification-token:{token}
24 小时过期（EMAIL_VERIFICATION_TOKEN_EXPIRATION_SECONDS）
过期后 KV 自动删除，查询时返回 null

发送验证邮件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


// src/utils/email-verification.ts

export async function sendUserVerificationEmail({
 userId,
 email,
 username,
}: SendUserVerificationEmailParams) {
 const verificationToken = await createExpiringToken({
 key: getVerificationTokenKey,
 expiresInSeconds: EMAIL_VERIFICATION_TOKEN_EXPIRATION_SECONDS,
 payload: { userId },
 createToken: createId,
 });

 await sendVerificationEmail({
 email,
 verificationToken,
 username,
 });
}

sendVerificationEmail 通过 Cloudflare 的邮件服务发送，包含验证链接：

1

https://yourapp.com/verify-email?token=xxx

验证 Token

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


// src/app/(auth)/verify-email/verify-email.action.ts

export const verifyEmailAction = actionClient
 .inputSchema(/* ... */)
 .action(async ({ parsedInput: input }) => {
 const { token } = input;

 // 1. 从 KV 获取 token
 const payload = await getValidExpiringToken({
 token,
 key: getVerificationTokenKey,
 notFoundError: {
 code: "NOT_FOUND",
 message: "Invalid or expired verification token",
 },
 });

 // 2. 更新用户的 emailVerified 字段
 const db = getDB();
 await db
 .update(userTable)
 .set({ emailVerified: new Date() })
 .where(eq(userTable.id, payload.userId));

 // 3. 删除已使用的 token
 await deleteExpiringToken({
 token,
 key: getVerificationTokenKey,
 });

 return { success: true };
 });

关键点：

验证成功后立即删除 token，防止重复使用
如果 token 不存在或已过期，返回明确错误
不依赖 token 中的 userId 做身份验证（只是更新 emailVerified）

重发限制

在用户设置页面可以重发验证邮件，但需要限流：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


export const sendVerificationAction = actionClient
 .action(async () => {
 return withRateLimit(async () => {
 const session = await requireVerifiedEmail({
 requireVerified: false, // 允许未验证用户访问
 });

 if (session.user.emailVerified) {
 throw new ActionError("CONFLICT", "Email already verified");
 }

 await sendUserVerificationEmail({
 userId: session.user.id,
 email: session.user.email!,
 username: session.user.firstName || session.user.email!,
 });

 return { success: true };
 }, RATE_LIMITS.EMAIL); // 每小时最多 10 次
 });

前端验证状态管理

用户登录后，如果邮箱未验证，会弹出一个验证提示对话框：

1
2
3
4


// src/components/email-verification-dialog.tsx
// 检查 session.user.emailVerified 是否为 null
// 如果未验证 → 显示对话框，提供"重发邮件"按钮
// 如果已验证 → 不显示

总结

KV 存储 token，利用 expirationTtl 自动过期，零维护成本
验证后立即删除 token，防止重复使用
重发邮件有限流保护（每小时 10 次）
前端通过 emailVerified 字段判断是否显示验证提示

Token on HanGR的碎碎念