Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
feat(2FA): add core library functions for TOTP, backup codes and rate limiting
Rudy B.683b956b9faa
diff --git a/src/lib/two-factor/backup-codes.ts b/src/lib/two-factor/backup-codes.tsnew file mode 100644index 000000000..a201cf24e--- /dev/null+++ b/src/lib/two-factor/backup-codes.ts@@ -0,0 +1,31 @@+import { randomBytes } from 'crypto';+import bcrypt from 'bcryptjs';++const BACKUP_CODE_COUNT = 10;+const BCRYPT_ROUNDS = 10;++export async function generateBackupCodes(): Promise<{+ plaintext: Array<string>;+ hashed: Array<string>;+}> {+ const plaintext = Array.from(+ { length: BACKUP_CODE_COUNT },+ () =>+ randomBytes(5).toString('hex').toUpperCase() ++ '-' ++ randomBytes(5).toString('hex').toUpperCase(),+ );+ const hashed = await Promise.all(plaintext.map(code => bcrypt.hash(code, BCRYPT_ROUNDS)));+ return { plaintext, hashed };+}++export async function verifyBackupCode(+ inputCode: string,+ storedHashes: Array<string>,+): Promise<number | null> {+ for (let i = 0; i < storedHashes.length; i++) {+ const match = await bcrypt.compare(inputCode.toUpperCase(), storedHashes[i]);+ if (match) return i;+ }+ return null;+}diff --git a/src/lib/two-factor/crypto.ts b/src/lib/two-factor/crypto.tsnew file mode 100644index 000000000..009109e77--- /dev/null+++ b/src/lib/two-factor/crypto.ts@@ -0,0 +1,39 @@+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from 'crypto';++const ALGORITHM = 'aes-256-gcm';++/** Loads and validates the 256-bit encryption key from TWO_FACTOR_ENCRYPTION_KEY. */+function getKey(): Buffer {+ const hex = process.env.TWO_FACTOR_ENCRYPTION_KEY;+ if (!hex || hex.length !== 64) throw new Error('TWO_FACTOR_ENCRYPTION_KEY is missing or invalid');+ return Buffer.from(hex, 'hex');+}++/** Encrypts a TOTP secret using AES-256-GCM. Returns `ciphertext:iv:authTag` as hex. */+export function encryptSecret(plaintext: string): string {+ const key = getKey();+ const iv = randomBytes(12);+ const cipher = createCipheriv(ALGORITHM, key, iv);+ const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);+ const authTag = cipher.getAuthTag();+ return `${encrypted.toString('hex')}:${iv.toString('hex')}:${authTag.toString('hex')}`;+}++/** Decrypts a TOTP secret previously encrypted by {@link encryptSecret}. */+export function decryptSecret(stored: string): string {+ const key = getKey();+ const [ciphertextHex, ivHex, authTagHex] = stored.split(':');+ const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(ivHex, 'hex'));+ decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));+ const decrypted = Buffer.concat([+ decipher.update(Buffer.from(ciphertextHex, 'hex')),+ decipher.final(),+ ]);+ return decrypted.toString('utf8');+}++/** Compares two strings in constant time to prevent timing attacks. */+export function constantTimeEqual(a: string, b: string): boolean {+ if (a.length !== b.length) return false;+ return timingSafeEqual(Buffer.from(a), Buffer.from(b));+}diff --git a/src/lib/two-factor/rate-limit.ts b/src/lib/two-factor/rate-limit.tsnew file mode 100644index 000000000..9671549df--- /dev/null+++ b/src/lib/two-factor/rate-limit.ts@@ -0,0 +1,31 @@+import prisma from '@/lib/prisma';++const MAX_ATTEMPTS = 5;+const LOCKOUT_MINUTES = 15;++export async function checkRateLimit(+ userId: string,+): Promise<{ allowed: boolean; lockedUntil?: Date }> {+ const record = await prisma.client.twoFactorRateLimit.findUnique({ where: { userId } });+ if (!record) return { allowed: true };+ if (record.lockedUntil && record.lockedUntil > new Date()) {+ return { allowed: false, lockedUntil: record.lockedUntil };+ }+ return { allowed: true };+}++export async function recordFailedAttempt(userId: string): Promise<void> {+ const record = await prisma.client.twoFactorRateLimit.upsert({+ where: { userId },+ update: { attempts: { increment: 1 }, updatedAt: new Date() },+ create: { userId, attempts: 1, updatedAt: new Date() },+ });+ if (record.attempts >= MAX_ATTEMPTS) {+ const lockedUntil = new Date(Date.now() + LOCKOUT_MINUTES * 60 * 1000);+ await prisma.client.twoFactorRateLimit.update({ where: { userId }, data: { lockedUntil } });+ }+}++export async function resetRateLimit(userId: string): Promise<void> {+ await prisma.client.twoFactorRateLimit.deleteMany({ where: { userId } });+}diff --git a/src/lib/two-factor/replay-prevention.ts b/src/lib/two-factor/replay-prevention.tsnew file mode 100644index 000000000..46f8dc3f9--- /dev/null+++ b/src/lib/two-factor/replay-prevention.ts@@ -0,0 +1,24 @@+import prisma from '@/lib/prisma';++/** Records a one-time password as used so it cannot be reused within the next 90 seconds. */+export async function markOtpUsed(userId: string, otp: string): Promise<void> {+ const expiresAt = new Date(Date.now() + 90 * 1000);+ await prisma.client.twoFactorOtpUsed.upsert({+ where: { userId_otp: { userId, otp } },+ update: { expiresAt },+ create: { userId, otp, expiresAt },+ });+}++/** Returns true if this one-time password was already used recently, indicating a replay attack. Expired records are cleaned up automatically. */+export async function isOtpReplayed(userId: string, otp: string): Promise<boolean> {+ const record = await prisma.client.twoFactorOtpUsed.findUnique({+ where: { userId_otp: { userId, otp } },+ });+ if (!record) return false;+ if (record.expiresAt < new Date()) {+ await prisma.client.twoFactorOtpUsed.delete({ where: { userId_otp: { userId, otp } } });+ return false;+ }+ return true;+}diff --git a/src/lib/two-factor/totp.ts b/src/lib/two-factor/totp.tsnew file mode 100644index 000000000..b5cbe6c48--- /dev/null+++ b/src/lib/two-factor/totp.ts@@ -0,0 +1,23 @@+import { generateSecret, generateURI, verify } from 'otplib';+import qrcode from 'qrcode';++export function generateTotpSecret(): string {+ return generateSecret();+}++export function generateOtpAuthUri(secret: string, userEmail: string): string {+ return generateURI({+ issuer: 'Umami',+ label: userEmail,+ secret,+ });+}++export async function generateQrCodeDataUrl(otpAuthUri: string): Promise<string> {+ return qrcode.toDataURL(otpAuthUri, { errorCorrectionLevel: 'H' });+}++export async function verifyTotp(token: string, secret: string): Promise<boolean> {+ const result = await verify({ secret, token });+ return result.valid;+}