/** * Two-factor authentication helpers: 6-digit codes delivered by email or * WhatsApp, and "trust this device" tokens that let a browser skip the code. * * Neither the code nor the device token is stored in the clear — only an * HMAC keyed with JWT_SECRET, so a leaked database row can't be replayed. */ const crypto = require('crypto'); const prisma = require('../config/db'); const { describeUserAgent } = require('./userAgent'); const CODE_TTL_MS = 10 * 60 * 1000; // a code is valid for 10 minutes const MAX_ATTEMPTS = 5; // wrong guesses allowed per code const RESEND_COOLDOWN_MS = 60 * 1000; // minimum gap between sends const CHALLENGE_MAX_AGE_MS = 30 * 60 * 1000; // after this, log in again rather than resend const TRUSTED_DEVICE_TTL_MS = 30 * 24 * 60 * 60 * 1000; const METHODS = ['email', 'whatsapp']; // Application error carrying the HTTP status the controller should respond with. function fail(message, statusCode = 400) { const err = new Error(message); err.statusCode = statusCode; return err; } function generateCode() { return String(crypto.randomInt(0, 1000000)).padStart(6, '0'); } function hmac(value) { return crypto.createHmac('sha256', process.env.JWT_SECRET || '').update(String(value)).digest('hex'); } // Namespaced so a code hash can never collide with a device-token hash. const hashCode = (code) => hmac(`2fa-code:${code}`); const hashDeviceToken = (token) => hmac(`2fa-device:${token}`); function safeEqual(a, b) { const ba = Buffer.from(String(a)); const bb = Buffer.from(String(b)); return ba.length === bb.length && crypto.timingSafeEqual(ba, bb); } function hasRealEmail(user) { return !!(user?.email && !user.email.endsWith('@guest.local') && !user.email.endsWith('@deleted.invalid') && !user.email.endsWith('@deleted.local')); } function maskEmail(email) { const [local, domain] = String(email || '').split('@'); if (!local || !domain) return '•••'; return `${local[0]}•••@${domain}`; } function maskPhone(phone) { const digits = String(phone || '').replace(/\D/g, ''); return `••• ••• ${digits.slice(-4)}`; } /** Channels this user could receive a code on right now. */ async function availableMethods(user) { const { isValidZAPhone, isConfigured } = require('./whatsapp'); const methods = []; if (hasRealEmail(user)) methods.push('email'); if (isValidZAPhone(user?.phoneNumber) && (await isConfigured())) methods.push('whatsapp'); return methods; } /** * Sends the code and reports where it actually went. A WhatsApp failure (session * disconnected, not configured) falls back to email so a user is never locked out * by the WhatsApp gateway being down. Throws when no channel could deliver. * Pass `allowFallback: false` when the point is to prove the chosen channel works. */ async function deliverCode(user, method, code, { allowFallback = true } = {}) { const { getSettingSync } = require('./settingsCache'); const orgName = getSettingSync('org_name', process.env.ORG_NAME || 'Cross Code'); if (process.env.NODE_ENV !== 'production') { console.info(`[2fa][dev] code for ${user.email}: ${code}`); } if (method === 'whatsapp') { const { isValidZAPhone, isConfigured, sendText } = require('./whatsapp'); const { buildWATwoFactorCode } = require('./waMessages'); try { // sendText silently no-ops when WhatsApp isn't set up, so check first. if (!isValidZAPhone(user.phoneNumber) || !(await isConfigured())) throw new Error('WhatsApp unavailable'); await sendText(user.phoneNumber, buildWATwoFactorCode({ name: user.name, code })); return { method: 'whatsapp', destination: maskPhone(user.phoneNumber) }; } catch (e) { console.warn('[2fa] WhatsApp code failed:', e?.message || e); if (!allowFallback) throw fail('We couldn\'t send a WhatsApp message right now. Please try again later or choose email.', 503); if (!hasRealEmail(user)) throw fail('We couldn\'t send your verification code. Please try again later.', 503); } } if (!hasRealEmail(user)) throw fail('We couldn\'t send your verification code. Please try again later.', 503); const { sendMail, buildTwoFactorCodeEmail } = require('./email'); try { await sendMail({ to: user.email, subject: `Your ${orgName} verification code`, ...buildTwoFactorCodeEmail({ name: user.name, code }) }); } catch (e) { console.warn('[2fa] Email code failed:', e?.message || e); throw fail('We couldn\'t send your verification code. Please try again later.', 503); } return { method: 'email', destination: maskEmail(user.email) }; } /** * Sends a fresh code and records the challenge. Any earlier challenge of the same * purpose for this user is discarded, so only the newest code works. */ async function createChallenge(user, purpose, method, options) { const code = generateCode(); const sent = await deliverCode(user, method, code, options); await prisma.twoFactorChallenge.deleteMany({ where: { userId: user.id, purpose } }); const challenge = await prisma.twoFactorChallenge.create({ data: { userId: user.id, purpose, method: sent.method, codeHash: hashCode(code), expiresAt: new Date(Date.now() + CODE_TTL_MS), }, }); return { challengeId: challenge.id, method: sent.method, destination: sent.destination }; } /** * Checks a submitted code. Returns the challenge (with its user) on success and * throws otherwise. Pass `userId` to also require the challenge belong to that user. */ async function verifyChallenge(challengeId, code, purpose, userId) { const invalid = () => fail('That code is invalid or has expired. Please request a new one.'); if (!challengeId || typeof challengeId !== 'string') throw invalid(); const submitted = String(code ?? '').replace(/\D/g, ''); // Count the attempt before comparing, atomically, so parallel guesses can't // slip past the attempt limit. const counted = await prisma.twoFactorChallenge.updateMany({ where: { id: challengeId, purpose, ...(userId ? { userId } : {}), usedAt: null, expiresAt: { gt: new Date() }, attempts: { lt: MAX_ATTEMPTS }, }, data: { attempts: { increment: 1 } }, }); if (counted.count !== 1) throw invalid(); const challenge = await prisma.twoFactorChallenge.findUnique({ where: { id: challengeId }, include: { user: true } }); if (!challenge || !safeEqual(challenge.codeHash, hashCode(submitted))) { const left = challenge ? MAX_ATTEMPTS - challenge.attempts : 0; throw fail(left > 0 ? `Incorrect code. ${left} attempt${left === 1 ? '' : 's'} left.` : 'Too many incorrect attempts. Please request a new code.'); } // Single use — if two requests race with the right code, only one wins. const used = await prisma.twoFactorChallenge.updateMany({ where: { id: challengeId, usedAt: null }, data: { usedAt: new Date() }, }); if (used.count !== 1) throw invalid(); return challenge; } /** Replaces the code on an existing challenge and sends it again. */ async function resendChallenge(challengeId, purpose, userId) { const expired = () => fail('This verification has expired. Please start again.'); if (!challengeId || typeof challengeId !== 'string') throw expired(); const challenge = await prisma.twoFactorChallenge.findUnique({ where: { id: challengeId }, include: { user: true } }); if (!challenge || challenge.purpose !== purpose || challenge.usedAt || (userId && challenge.userId !== userId)) throw expired(); if (Date.now() - challenge.createdAt.getTime() > CHALLENGE_MAX_AGE_MS) throw expired(); const wait = RESEND_COOLDOWN_MS - (Date.now() - challenge.lastSentAt.getTime()); if (wait > 0) throw fail(`Please wait ${Math.ceil(wait / 1000)} seconds before requesting another code.`, 429); // Claim the send slot first so two simultaneous resends can't both go out. const claimed = await prisma.twoFactorChallenge.updateMany({ where: { id: challengeId, lastSentAt: challenge.lastSentAt, usedAt: null }, data: { lastSentAt: new Date() }, }); if (claimed.count !== 1) throw fail('Please wait before requesting another code.', 429); const code = generateCode(); const sent = await deliverCode(challenge.user, challenge.method, code); await prisma.twoFactorChallenge.update({ where: { id: challengeId }, data: { codeHash: hashCode(code), method: sent.method, attempts: 0, expiresAt: new Date(Date.now() + CODE_TTL_MS) }, }); return { challengeId, method: sent.method, destination: sent.destination }; } /** Remembers this browser for 30 days. Returns the raw token to hand to the client. */ async function issueTrustedDevice(userId, userAgent) { const token = crypto.randomBytes(32).toString('hex'); await prisma.trustedDevice.deleteMany({ where: { userId, expiresAt: { lt: new Date() } } }); await prisma.trustedDevice.create({ data: { userId, tokenHash: hashDeviceToken(token), device: describeUserAgent(userAgent), expiresAt: new Date(Date.now() + TRUSTED_DEVICE_TTL_MS), }, }); return token; } /** True when `token` is an unexpired trusted-device token belonging to this user. */ async function isTrustedDevice(userId, token) { if (!token || typeof token !== 'string') return false; const row = await prisma.trustedDevice.findUnique({ where: { tokenHash: hashDeviceToken(token) } }); if (!row || row.userId !== userId || row.expiresAt <= new Date()) return false; prisma.trustedDevice.update({ where: { id: row.id }, data: { lastUsedAt: new Date() } }).catch(() => {}); return true; } /** Forgets every trusted device — call whenever credentials or sessions are reset. */ async function clearTrustedDevices(userId) { try { await prisma.trustedDevice.deleteMany({ where: { userId } }); } catch (e) { console.error('Failed to clear trusted devices:', e?.message); } } module.exports = { METHODS, MAX_ATTEMPTS, generateCode, hashCode, hashDeviceToken, maskEmail, maskPhone, hasRealEmail, availableMethods, createChallenge, verifyChallenge, resendChallenge, issueTrustedDevice, isTrustedDevice, clearTrustedDevices, };