import { randomInt } from "node:crypto"; import { Minute } from "@shared/utils/time"; import Redis from "@server/storage/redis"; import { safeEqual } from "./crypto"; /** * This class manages verification codes for email authentication. * It stores and retrieves 6-digit codes in Redis with a 10-minute TTL. */ export class VerificationCode { /** * Redis client instance (lazy initialized) */ private static get redis() { return Redis.defaultClient; } /** * TTL for verification codes in milliseconds (10 minutes) */ private static readonly TTL = Minute.ms * 10; /** * Maximum number of verification attempts before the code is deleted */ private static readonly MAX_ATTEMPTS = 10; /** * Prefix for Redis keys */ private static readonly KEY_PREFIX = "email_verification_code:"; /** * Prefix for Redis attempt counter keys */ private static readonly ATTEMPTS_PREFIX = "email_verification_attempts:"; /** * Generate a random 6-digit code, drawn uniformly from the full range of * possible values and left-padded to a fixed six characters. * * @returns A string representing a 6-digit code. */ public static generate(): string { return randomInt(0, 1000000).toString().padStart(6, "0"); } /** * Store a verification code in Redis with a 10-minute TTL * * @param teamId The team the code is being issued for * @param email The email address associated with the code * @param code The 6-digit verification code * @returns Promise resolving to true if successful */ public static async store( teamId: string, email: string, code: string ): Promise { const key = this.getKey(teamId, email); await this.redis.set(key, code, "PX", this.TTL); return true; } /** * Retrieve a verification code from Redis * * @param teamId The team the code was issued for * @param email The email address associated with the code * @returns Promise resolving to the code or undefined if not found */ public static async retrieve( teamId: string, email: string ): Promise { const key = this.getKey(teamId, email); return (await this.redis.get(key)) ?? undefined; } /** * Verify if a given code matches the stored code for an email within a team. * * @param teamId The team the code was issued for * @param email The email address associated with the code * @param code The code to verify * @returns Promise resolving to true if the code matches, false otherwise */ public static async verify( teamId: string, email: string, code: string ): Promise { const storedCode = await this.retrieve(teamId, email); if (!storedCode) { return false; } const attemptsKey = this.getAttemptsKey(teamId, email); const attempts = await this.redis.incr(attemptsKey); if (attempts === 1) { await this.redis.pexpire(attemptsKey, this.TTL); } if (attempts > this.MAX_ATTEMPTS) { await this.delete(teamId, email); return false; } return safeEqual(storedCode, code); } /** * Delete a verification code from Redis * * @param teamId The team the code was issued for * @param email The email address associated with the code * @returns Promise resolving to true if successful */ public static async delete(teamId: string, email: string): Promise { const key = this.getKey(teamId, email); const attemptsKey = this.getAttemptsKey(teamId, email); await this.redis.del(key, attemptsKey); return true; } /** * Get the Redis key for a code scoped to a team and email address. * * @param teamId The team the code was issued for * @param email The email address * @returns The Redis key */ private static getKey(teamId: string, email: string): string { return `${this.KEY_PREFIX}${teamId}:${email.trim().toLowerCase()}`; } /** * Get the Redis key for tracking verification attempts. * * @param teamId The team the code was issued for * @param email The email address. * @returns the Redis key for attempts. */ private static getAttemptsKey(teamId: string, email: string): string { return `${this.ATTEMPTS_PREFIX}${teamId}:${email.trim().toLowerCase()}`; } }