games_app/backend/src/services/authService.ts

888 lines
32 KiB
TypeScript

/**
* Authentication and user identity service.
* Handles registration, login, JWT issuance, profile management, password changes, and TOTP 2FA.
*/
import argon2 from 'argon2';
import jwt from 'jsonwebtoken';
import { authenticator } from 'otplib';
import { randomBytes } from 'crypto';
import * as QRCode from 'qrcode';
import { config } from '../config';
import { hashForIndex, hashForPhone, hashToken, decrypt, encrypt } from '../utils/crypto';
import * as userRepository from '../repositories/userRepository';
import * as refreshTokenRepository from '../repositories/refreshTokenRepository';
import * as auditLogRepository from '../repositories/auditLogRepository';
import * as totpRecoveryRepository from '../repositories/totpRecoveryRepository';
import * as settingsRepository from '../repositories/settingsRepository';
import { queueUserAdminStatsRefresh } from './userAdminStatsService';
import * as loginLockoutService from './loginLockoutService';
import { logSecurityEvent } from '../utils/securityAudit';
import { sendVerificationAfterRegister } from './emailVerificationService';
import * as referralRepository from '../repositories/referralRepository';
import * as referralService from './referralService';
import * as countryService from './countryService';
import { mergeVisitorSupportForUser } from './supportService';
import { registerLoginFingerprint } from '../repositories/loginFingerprintRepository';
import * as securityNotificationService from './securityNotificationService';
import * as captchaService from './captchaService';
import { assessLoginRisk, recordLoginRisk } from './loginRiskService';
import { enforceConcurrentSessionLimit } from './sessionService';
import { SystemSettings } from '../models';
import { parseUserGender, type UserGender } from '../models/userGender';
import { JwtPayload, RoleName } from '../types';
import * as roleRepository from '../repositories/roleRepository';
import { hasAdminAccess } from '../utils/roleAccess';
import { v4 as uuidv4 } from 'uuid';
authenticator.options = { digits: 6, step: 30 };
const RECOVERY_CODE_COUNT = 10;
function generateRecoveryCodes(): string[] {
const codes: string[] = [];
for (let i = 0; i < RECOVERY_CODE_COUNT; i++) {
codes.push(randomBytes(5).toString('hex').toUpperCase());
}
return codes;
}
function normalizeRecoveryCode(code: string): string {
return code.trim().replace(/\s+/g, '').toUpperCase();
}
async function verifySecondFactor(userId: string, code?: string): Promise<'totp' | 'recovery'> {
const user = await userRepository.findById(userId);
if (!user || !user.totp_enabled) throw new Error('2FA not enabled');
if (!code?.trim()) throw new Error('2FA required');
const secret = user.totp_secret_encrypted ? decrypt(user.totp_secret_encrypted) : '';
if (authenticator.verify({ token: code.trim(), secret })) return 'totp';
const normalized = normalizeRecoveryCode(code);
if (normalized.length >= 8) {
const ok = await totpRecoveryRepository.consumeCode(userId, hashForIndex(normalized));
if (ok) return 'recovery';
}
throw new Error('Invalid 2FA code');
}
/** Builds JWT claims from current DB roles and permissions. */
export async function buildJwtPayload(user: {
id: string;
email_hash: string;
token_version?: number;
}): Promise<JwtPayload> {
const roles = await roleRepository.getUserRoleNames(user.id);
const permissions = await roleRepository.getUserPermissions(user.id);
const primaryRole = roleRepository.resolvePrimaryRole(roles);
return {
userId: user.id,
emailHash: user.email_hash,
roles,
permissions,
primaryRole,
role: primaryRole,
tv: user.token_version ?? 1,
};
}
/** Normalizes legacy JWT payloads that only contain a single `role`. */
export function normalizeJwtPayload(decoded: JwtPayload): JwtPayload {
const roles =
decoded.roles?.length ? decoded.roles : decoded.role ? [decoded.role] : (['user'] as RoleName[]);
const primaryRole = roleRepository.resolvePrimaryRole(roles);
return {
...decoded,
roles,
permissions: decoded.permissions ?? [],
primaryRole,
role: primaryRole,
};
}
/**
* Converts a duration string (e.g. "7d", "15m") to milliseconds.
* Falls back to 7 days when the format is unrecognized.
* @param expiry Duration string with numeric value and unit (s, m, h, d)
* @returns Duration in milliseconds
*/
function parseExpiryToMs(expiry: string): number {
const m = expiry.match(/^(\d+)(m|h|d|s)$/i);
if (!m) return 7 * 24 * 60 * 60 * 1000;
const n = parseInt(m[1], 10);
const unit = m[2].toLowerCase();
if (unit === 's') return n * 1000;
if (unit === 'm') return n * 60 * 1000;
if (unit === 'h') return n * 60 * 60 * 1000;
if (unit === 'd') return n * 24 * 60 * 60 * 1000;
return 7 * 24 * 60 * 60 * 1000;
}
/**
* Validates a password against the system password policy from settings.
* @param password Plain-text password to validate
* @param policy System settings containing password rules
* @throws {Error} When the password fails any configured policy rule
*/
export function validatePassword(password: string, policy: SystemSettings): void {
if (password.length < policy.password_min_length) {
throw new Error(`Password must be at least ${policy.password_min_length} characters`);
}
if (policy.password_require_uppercase && !/[A-Z]/.test(password)) {
throw new Error('Password must include at least one uppercase letter');
}
if (policy.password_require_lowercase && !/[a-z]/.test(password)) {
throw new Error('Password must include at least one lowercase letter');
}
if (policy.password_require_number && !/\d/.test(password)) {
throw new Error('Password must include at least one number');
}
if (policy.password_require_special && !/[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/.test(password)) {
throw new Error('Password must include at least one special character');
}
}
/**
* Registers a new user with profile, country, and optional referral code.
*/
export async function register(input: {
email: string;
password: string;
fullName: string;
phone?: string;
countryOfResidence: string;
nationality?: string;
gender: string;
referralCode?: string;
registrationIp?: string;
userAgent?: string;
visitorSupportToken?: string | null;
}): Promise<{ userId: string; referralCode: string; emailVerificationRequired: boolean }> {
const policy = await settingsRepository.getSettings();
validatePassword(input.password, policy);
const normalizedEmail = input.email.trim().toLowerCase();
if (!normalizedEmail) throw new Error('Email is required');
const fullName = input.fullName.trim();
if (fullName.length < 2) throw new Error('Full name is required');
const country = input.countryOfResidence.trim().toUpperCase();
if (!/^[A-Z]{2}$/.test(country)) {
throw new Error('Country of residence must be a 2-letter ISO code (e.g. FR, US)');
}
await countryService.assertCountryAllowedForRegistration(country);
const nationality = input.nationality?.trim().toUpperCase() || null;
if (nationality && !/^[A-Z]{2}$/.test(nationality)) {
throw new Error('Nationality must be a 2-letter ISO code');
}
const gender = parseUserGender(input.gender);
const emailHash = hashForIndex(normalizedEmail);
const existing = await userRepository.findByEmailHash(emailHash);
if (existing) {
throw new Error('Email is already registered');
}
let phoneHash: string | null = null;
let phoneEncrypted: string | null = null;
if (input.phone?.trim()) {
const normalizedPhone = input.phone.trim();
phoneHash = hashForPhone(normalizedPhone);
const existingPhone = await userRepository.findByPhoneHash(phoneHash);
if (existingPhone) throw new Error('Phone number already registered');
phoneEncrypted = encrypt(normalizedPhone);
}
const referredByUserId = await referralService.resolveReferrerId(input.referralCode);
if (referredByUserId) {
await referralService.assertReferrerEligible(referredByUserId);
}
const nameParts = fullName.split(/\s+/);
const firstName = nameParts[0] ?? fullName;
const lastName = nameParts.length > 1 ? nameParts.slice(1).join(' ') : null;
const passwordHash = await argon2.hash(input.password, { type: argon2.argon2id });
const userReferralCode = await referralRepository.generateUniqueReferralCode();
const user = await userRepository.create({
emailHash,
emailEncrypted: encrypt(normalizedEmail),
passwordHash,
roleId: 1,
firstName,
lastName,
phoneHash,
phoneEncrypted,
countryOfResidence: country,
nationality,
gender,
referralCode: userReferralCode,
referredByUserId,
registrationIp: input.registrationIp?.trim() || null,
});
await auditLogRepository.create({
userId: user.id,
action: 'register',
resourceType: 'user',
resourceId: user.id,
ipAddress: input.registrationIp ?? null,
userAgent: input.userAgent ?? null,
metadata: referredByUserId ? { referred_by_user_id: referredByUserId } : null,
});
void sendVerificationAfterRegister(user.id);
void mergeVisitorSupportForUser(user.id, input.visitorSupportToken);
return {
userId: user.id,
referralCode: userReferralCode,
emailVerificationRequired: true,
};
}
/**
* Authenticates a user and issues access and refresh tokens.
* @param email User email for lookup
* @param password Plain-text password
* @param totpCode Optional TOTP code when 2FA is enabled
* @param auditContext Optional IP and user agent for login audit log
* @returns Access token, refresh token, expiry seconds, and basic user info
* @throws {Error} On invalid credentials, disabled/locked account, or failed 2FA
*/
export async function login(
email: string,
password: string,
totpCode?: string,
auditContext?: { ipAddress?: string; userAgent?: string; visitorSupportToken?: string | null },
captchaToken?: string
): Promise<{
accessToken: string;
refreshToken: string;
expiresIn: number;
user: {
id: string;
emailHash: string;
role: RoleName;
roles: RoleName[];
permissions: string[];
primaryRole: RoleName;
};
}> {
const emailHash = hashForIndex(email);
const user = await userRepository.findByEmailHash(emailHash);
const auditIp = auditContext?.ipAddress;
const auditUa = auditContext?.userAgent;
if (!user) {
logSecurityEvent('login_failed', {
ipAddress: auditIp ?? null,
userAgent: auditUa ?? null,
metadata: { reason: 'invalid_credentials' },
});
throw new Error('Invalid credentials');
}
if (user.deleted_at) {
logSecurityEvent('login_failed', {
userId: user.id,
ipAddress: auditIp ?? null,
userAgent: auditUa ?? null,
metadata: { reason: 'account_deleted' },
});
throw new Error('Invalid credentials');
}
try {
await loginLockoutService.assertLoginNotLocked(user.id);
} catch (e) {
logSecurityEvent('login_failed', {
userId: user.id,
ipAddress: auditIp ?? null,
userAgent: auditUa ?? null,
metadata: { reason: 'account_locked' },
});
throw e;
}
const settings = await settingsRepository.getSettings();
const failedCount = await userRepository.getFailedLoginCount(user.id);
const afterFailures = settings.login_captcha_after_failures;
if (afterFailures > 0 && failedCount >= afterFailures) {
try {
await captchaService.verifyCaptchaToken(captchaToken, auditIp);
} catch (e) {
throw captchaService.withCaptchaChallenge(e as Error & { code?: string });
}
}
if (user.is_enabled === false) {
logSecurityEvent('login_failed', {
userId: user.id,
ipAddress: auditIp ?? null,
userAgent: auditUa ?? null,
metadata: { reason: 'account_disabled' },
});
throw new Error('Account is disabled');
}
if (user.is_account_non_locked === false) {
logSecurityEvent('login_failed', {
userId: user.id,
ipAddress: auditIp ?? null,
userAgent: auditUa ?? null,
metadata: { reason: 'account_locked_admin' },
});
throw new Error('Account is locked');
}
if (user.is_account_non_expired === false) {
throw new Error('Account has expired');
}
if (user.is_credentials_non_expired === false) {
throw new Error('Credentials have expired');
}
const ok = await argon2.verify(user.password_hash, password);
if (!ok) {
await loginLockoutService.recordFailedLogin(user.id, {
ipAddress: auditIp,
userAgent: auditUa,
reason: 'invalid_password',
});
await loginLockoutService.assertLoginNotLocked(user.id);
throw new Error('Invalid credentials');
}
if (settings.require_email_verification_for_login && !user.email_verified) {
const err = new Error(
'Please verify your email before signing in. Check your inbox for the confirmation link.'
) as Error & { code?: string };
err.code = 'EMAIL_NOT_VERIFIED';
throw err;
}
if (user.totp_enabled) {
if (!totpCode) throw new Error('2FA required');
try {
await verifySecondFactor(user.id, totpCode);
} catch {
await loginLockoutService.recordFailedLogin(user.id, {
ipAddress: auditIp,
userAgent: auditUa,
reason: 'invalid_2fa',
});
await loginLockoutService.assertLoginNotLocked(user.id);
throw new Error('Invalid 2FA code');
}
}
await loginLockoutService.clearLoginFailures(user.id);
const payload = await buildJwtPayload(user);
const accessExpiry = settings.access_token_expiry || config.jwt.accessExpiry;
const accessToken = jwt.sign(payload, config.jwt.secret, { expiresIn: accessExpiry } as jwt.SignOptions);
const refreshToken = uuidv4();
const refreshExpiryMs = parseExpiryToMs(settings.refresh_token_expiry || config.jwt.refreshExpiry);
const expiresAt = new Date(Date.now() + refreshExpiryMs);
await refreshTokenRepository.create(user.id, hashToken(refreshToken), expiresAt, {
ipAddress: auditContext?.ipAddress,
userAgent: auditContext?.userAgent,
});
await enforceConcurrentSessionLimit(user.id, auditContext);
if (auditContext) {
await auditLogRepository.create({
userId: user.id,
action: 'login',
ipAddress: auditContext.ipAddress,
userAgent: auditContext.userAgent,
});
queueUserAdminStatsRefresh(user.id);
const fingerprint = await registerLoginFingerprint(
user.id,
auditContext.ipAddress,
auditContext.userAgent
);
const notifyCtx = {
ipAddress: auditContext.ipAddress,
userAgent: auditContext.userAgent,
countryCode: fingerprint.countryCode,
};
if (fingerprint.isNewDevice) {
void securityNotificationService.notifyNewLogin(user.id, notifyCtx);
}
if (fingerprint.isNewCountry && fingerprint.countryCode) {
void securityNotificationService.notifyNewCountryLogin(user.id, notifyCtx);
}
const risk = assessLoginRisk(fingerprint);
void recordLoginRisk(user.id, risk, notifyCtx);
}
void mergeVisitorSupportForUser(user.id, auditContext?.visitorSupportToken);
const decoded = jwt.decode(accessToken) as { exp: number };
return {
accessToken,
refreshToken,
expiresIn: decoded.exp - Math.floor(Date.now() / 1000),
user: {
id: user.id,
emailHash: user.email_hash,
role: payload.primaryRole,
roles: payload.roles,
permissions: payload.permissions,
primaryRole: payload.primaryRole,
},
};
}
/**
* Issues a new access/refresh token pair from a valid refresh token (rotation).
* @param refreshToken Opaque refresh token issued at login
* @returns New access token, rotated refresh token, and remaining lifetime in seconds
* @throws {Error} When refresh token is invalid or user no longer exists / is disabled
*/
export async function refreshTokens(refreshToken: string): Promise<{
accessToken: string;
refreshToken: string;
expiresIn: number;
}> {
const tokenHash = hashToken(refreshToken);
const row = await refreshTokenRepository.findByTokenHash(tokenHash);
if (!row) throw new Error('Invalid refresh token');
const user = await userRepository.findById(row.user_id);
if (!user) throw new Error('User not found');
if (user.deleted_at) throw new Error('Account is not available');
if (user.is_enabled === false) throw new Error('Account is disabled');
if (user.is_account_non_locked === false) throw new Error('Account is locked');
if (user.is_account_non_expired === false) throw new Error('Account has expired');
if (user.is_credentials_non_expired === false) throw new Error('Credentials have expired');
await refreshTokenRepository.deleteByTokenHash(tokenHash);
const settings = await settingsRepository.getSettings();
const accessExpiry = settings.access_token_expiry || config.jwt.accessExpiry;
const payload = await buildJwtPayload(user);
const accessToken = jwt.sign(payload, config.jwt.secret, { expiresIn: accessExpiry } as jwt.SignOptions);
const newRefreshToken = uuidv4();
const refreshExpiryMs = parseExpiryToMs(settings.refresh_token_expiry || config.jwt.refreshExpiry);
const expiresAt = new Date(Date.now() + refreshExpiryMs);
await refreshTokenRepository.create(user.id, hashToken(newRefreshToken), expiresAt);
await enforceConcurrentSessionLimit(user.id);
const decoded = jwt.decode(accessToken) as { exp: number };
return {
accessToken,
refreshToken: newRefreshToken,
expiresIn: decoded.exp - Math.floor(Date.now() / 1000),
};
}
/**
* Revokes the current refresh token (logout).
*/
export async function logout(
refreshToken: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<void> {
const tokenHash = hashToken(refreshToken);
const row = await refreshTokenRepository.findByTokenHash(tokenHash);
if (!row) return;
await refreshTokenRepository.deleteByTokenHash(tokenHash);
await auditLogRepository.create({
userId: row.user_id,
action: 'logout',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
});
}
/**
* Revokes all refresh tokens for the user (logout everywhere).
*/
export async function logoutAll(
userId: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<void> {
await refreshTokenRepository.deleteByUserId(userId);
await userRepository.incrementTokenVersion(userId);
await auditLogRepository.create({
userId,
action: 'logout_all',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
});
}
/**
* Returns decrypted profile fields for the authenticated user.
* @param userId User UUID
* @returns Profile fields (names, date of birth, email, phone)
* @throws {Error} When user is not found
*/
export async function getProfile(userId: string): Promise<{
id: string;
firstName: string | null;
middleName: string | null;
lastName: string | null;
dateOfBirth: string | null;
email: string | null;
phone: string | null;
countryOfResidence: string | null;
nationality: string | null;
gender: UserGender | null;
role: string;
emailVerified: boolean;
totpEnabled: boolean;
createdAt: string;
}> {
const row = await userRepository.getSelfProfileForUser(userId);
if (!row) throw new Error('User not found');
const dob = row.date_of_birth;
const createdAt =
row.created_at instanceof Date
? row.created_at.toISOString()
: String(row.created_at);
return {
id: row.id,
firstName: row.first_name ?? null,
middleName: row.middle_name ?? null,
lastName: row.last_name ?? null,
dateOfBirth: dob != null ? (typeof dob === 'string' ? dob : (dob as Date).toISOString().slice(0, 10)) : null,
email: row.email_encrypted ? decrypt(row.email_encrypted) : null,
phone: row.phone_encrypted ? decrypt(row.phone_encrypted) : null,
countryOfResidence: row.country_of_residence ?? null,
nationality: row.nationality ?? null,
gender: (row.gender as UserGender | null) ?? null,
role: row.role_name,
emailVerified: row.email_verified,
totpEnabled: row.totp_enabled,
createdAt,
};
}
/**
* Updates user profile fields; email and phone are re-hashed and encrypted.
* @param userId User UUID
* @param updates Partial profile updates (undefined fields are skipped)
* @throws {Error} When user not found, email/phone empty, or already used by another account
*/
export async function updateProfile(
userId: string,
updates: {
firstName?: string | null;
middleName?: string | null;
lastName?: string | null;
dateOfBirth?: string | null;
email?: string;
phone?: string | null;
countryOfResidence?: string | null;
nationality?: string | null;
gender?: string;
}
): Promise<void> {
const existing = await userRepository.findById(userId);
if (!existing) throw new Error('User not found');
const data: Parameters<typeof userRepository.updateProfile>[1] = {};
if (updates.firstName !== undefined) data.first_name = (updates.firstName ?? '').trim() || null;
if (updates.middleName !== undefined) data.middle_name = (updates.middleName ?? '').trim() || null;
if (updates.lastName !== undefined) data.last_name = (updates.lastName ?? '').trim() || null;
if (updates.dateOfBirth !== undefined) data.date_of_birth = (updates.dateOfBirth ?? '').trim() || null;
if (updates.email !== undefined) {
const newEmail = updates.email.trim().toLowerCase();
if (!newEmail) throw new Error('Email cannot be empty');
const newEmailHash = hashForIndex(newEmail);
const existingByEmail = await userRepository.findByEmailHash(newEmailHash);
if (existingByEmail && existingByEmail.id !== userId) {
throw new Error('Email is already in use by another account');
}
data.emailHash = newEmailHash;
data.emailEncrypted = encrypt(newEmail);
await userRepository.setEmailVerified(userId, false);
}
if (updates.phone !== undefined) {
if (updates.phone === null || updates.phone.trim() === '') {
data.phoneHash = null;
data.phoneEncrypted = null;
} else {
const normalized = updates.phone.trim();
const newPhoneHash = hashForPhone(normalized);
const existingByPhone = await userRepository.findByPhoneHash(newPhoneHash);
if (existingByPhone && existingByPhone.id !== userId) {
throw new Error('Phone number is already in use by another account');
}
data.phoneHash = newPhoneHash;
data.phoneEncrypted = encrypt(normalized);
}
}
if (updates.countryOfResidence !== undefined) {
const country = (updates.countryOfResidence ?? '').trim().toUpperCase();
if (!country) throw new Error('Country of residence is required');
if (!/^[A-Z]{2}$/.test(country)) {
throw new Error('Country of residence must be a 2-letter ISO code (e.g. FR, US)');
}
await countryService.assertCountryAllowedForRegistration(country);
data.country_of_residence = country;
}
if (updates.nationality !== undefined) {
if (updates.nationality === null || updates.nationality.trim() === '') {
data.nationality = null;
} else {
const nat = updates.nationality.trim().toUpperCase();
if (!/^[A-Z]{2}$/.test(nat)) {
throw new Error('Nationality must be a 2-letter ISO code');
}
data.nationality = nat;
}
}
if (updates.gender !== undefined) {
data.gender = parseUserGender(updates.gender);
}
if (Object.keys(data).length > 0) {
await userRepository.updateProfile(userId, data);
}
}
/**
* Changes the user's password after verifying the current one.
* @param userId User UUID
* @param currentPassword Existing plain-text password
* @param newPassword New plain-text password (validated against policy)
* @throws {Error} When user not found, current password wrong, or new password fails policy
*/
export async function changePassword(
userId: string,
currentPassword: string,
newPassword: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<void> {
const user = await userRepository.findById(userId);
if (!user) throw new Error('User not found');
const ok = await argon2.verify(user.password_hash, currentPassword);
if (!ok) throw new Error('Current password is incorrect');
const policy = await settingsRepository.getSettings();
validatePassword(newPassword, policy);
const passwordHash = await argon2.hash(newPassword, { type: argon2.argon2id });
await userRepository.updatePassword(userId, passwordHash);
await refreshTokenRepository.deleteByUserId(userId);
await auditLogRepository.create({
userId,
action: 'password_changed',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
});
void securityNotificationService.notifyPasswordChanged(userId, {
ipAddress: auditContext?.ipAddress,
userAgent: auditContext?.userAgent,
});
}
/**
* Generates a new TOTP secret and QR code for 2FA setup (not yet enabled until confirmed).
* @param userId User UUID
* @returns Base32 secret and data-URL QR code for authenticator apps
* @throws {Error} When user is not found
*/
export async function setupTotp(
userId: string,
opts?: { password?: string; totpCode?: string; auditContext?: { ipAddress?: string; userAgent?: string } }
): Promise<{ secret: string; qrCodeUrl: string }> {
const user = await userRepository.findById(userId);
if (!user) throw new Error('User not found');
if (user.totp_enabled) {
if (!opts?.password || !opts?.totpCode) {
throw new Error('Password and current 2FA code are required to reset 2FA setup');
}
const pwOk = await argon2.verify(user.password_hash, opts.password);
if (!pwOk) throw new Error('Current password is incorrect');
await verifySecondFactor(userId, opts.totpCode);
await totpRecoveryRepository.deleteCodesForUser(userId);
await userRepository.updateTotp(userId, null, false);
await auditLogRepository.create({
userId,
action: 'totp_setup_reset',
ipAddress: opts.auditContext?.ipAddress ?? null,
userAgent: opts.auditContext?.userAgent ?? null,
});
}
const secret = authenticator.generateSecret();
const encrypted = encrypt(secret);
const otpauth = authenticator.keyuri(user.email_hash, 'Prediqo', secret);
const qrCodeUrl = await QRCode.toDataURL(otpauth);
await userRepository.updateTotp(userId, encrypted, false);
await auditLogRepository.create({
userId,
action: 'totp_setup_started',
ipAddress: opts?.auditContext?.ipAddress ?? null,
userAgent: opts?.auditContext?.userAgent ?? null,
});
return { secret, qrCodeUrl };
}
/**
* Confirms and enables 2FA after the user verifies a TOTP code from setup.
* @param userId User UUID
* @param code Six-digit TOTP code from authenticator app
* @throws {Error} When 2FA was not set up or code is invalid
*/
export async function enableTotp(
userId: string,
code: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<{ recoveryCodes: string[] }> {
const user = await userRepository.findById(userId);
if (!user || !user.totp_secret_encrypted) throw new Error('2FA not set up');
const secret = decrypt(user.totp_secret_encrypted);
const valid = authenticator.verify({ token: code, secret });
if (!valid) throw new Error('Invalid 2FA code');
await userRepository.updateTotp(userId, user.totp_secret_encrypted, true);
const recoveryCodes = generateRecoveryCodes();
await totpRecoveryRepository.replaceCodesForUser(
userId,
recoveryCodes.map((c) => hashForIndex(normalizeRecoveryCode(c)))
);
await auditLogRepository.create({
userId,
action: 'totp_enabled',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
metadata: { recoveryCodesIssued: recoveryCodes.length },
});
void securityNotificationService.notifyTotpEnabled(userId, {
ipAddress: auditContext?.ipAddress,
userAgent: auditContext?.userAgent,
});
return { recoveryCodes };
}
/**
* Verifies TOTP for sensitive actions (e.g. transfer). No-op when 2FA is disabled
* unless platform policy requires withdrawal 2FA (see assertWithdrawalSecondFactor).
*/
export async function verifyTotp(userId: string, totpCode?: string): Promise<void> {
const user = await userRepository.findById(userId);
if (!user) throw new Error('User not found');
if (!user.totp_enabled) return;
await verifySecondFactor(userId, totpCode);
}
/**
* Enforces platform withdrawal/transfer 2FA policy.
* When require_withdrawal_2fa is enabled, user must have 2FA on and provide a valid code.
*/
export async function assertWithdrawalSecondFactor(userId: string, totpCode?: string): Promise<void> {
const settings = await settingsRepository.getSettings();
if (!settings.require_withdrawal_2fa) {
await verifyTotp(userId, totpCode);
return;
}
const user = await userRepository.findById(userId);
if (!user) throw new Error('User not found');
if (!user.totp_enabled) {
const err = new Error(
'2FA must be enabled before withdrawals or transfers. Enable two-factor authentication in your profile.'
) as Error & { code?: string };
err.code = 'WITHDRAWAL_2FA_REQUIRED';
throw err;
}
await verifySecondFactor(userId, totpCode);
}
/**
* Disables 2FA after verifying password and TOTP / recovery code.
*/
export async function disableTotp(
userId: string,
password: string,
code: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<void> {
const user = await userRepository.findById(userId);
if (!user) throw new Error('User not found');
if (!user.totp_enabled) throw new Error('2FA is not enabled');
const pwOk = await argon2.verify(user.password_hash, password);
if (!pwOk) throw new Error('Current password is incorrect');
await verifySecondFactor(userId, code);
await userRepository.updateTotp(userId, null, false);
await totpRecoveryRepository.deleteCodesForUser(userId);
await auditLogRepository.create({
userId,
action: 'totp_disabled',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
});
void securityNotificationService.notifyTotpDisabled(userId, {
ipAddress: auditContext?.ipAddress,
userAgent: auditContext?.userAgent,
});
}
/**
* Issues new recovery codes (invalidates previous). Requires valid TOTP.
*/
export async function regenerateRecoveryCodes(
userId: string,
totpCode: string,
auditContext?: { ipAddress?: string; userAgent?: string }
): Promise<{ recoveryCodes: string[] }> {
const user = await userRepository.findById(userId);
if (!user?.totp_enabled) throw new Error('2FA is not enabled');
const secret = user.totp_secret_encrypted ? decrypt(user.totp_secret_encrypted) : '';
if (!authenticator.verify({ token: totpCode, secret })) {
throw new Error('Invalid 2FA code');
}
const recoveryCodes = generateRecoveryCodes();
await totpRecoveryRepository.replaceCodesForUser(
userId,
recoveryCodes.map((c) => hashForIndex(normalizeRecoveryCode(c)))
);
await auditLogRepository.create({
userId,
action: 'totp_recovery_regenerated',
ipAddress: auditContext?.ipAddress ?? null,
userAgent: auditContext?.userAgent ?? null,
metadata: { count: recoveryCodes.length },
});
return { recoveryCodes };
}
/**
* Verifies and decodes a JWT access token.
* @param accessToken Signed JWT string
* @returns Decoded payload with userId, emailHash, and role
* @throws jwt.JsonWebTokenError When token is invalid or expired
*/
export async function verifyToken(accessToken: string): Promise<JwtPayload> {
const decoded = jwt.verify(accessToken, config.jwt.secret) as JwtPayload;
return normalizeJwtPayload(decoded);
}
/**
* Returns a guard function that throws if the JWT payload role is not allowed.
* @param allowed Roles permitted for the protected route
* @returns Callback that validates payload.role against allowed list
* @throws {Error} Forbidden when role is not in allowed
*/
export function requireRole(allowed: RoleName[]): (payload: JwtPayload) => void {
return (payload: JwtPayload) => {
const roles = payload.roles ?? (payload.role ? [payload.role] : []);
const ok =
allowed.some((r) => roles.includes(r)) ||
(allowed.includes('admin') && hasAdminAccess(payload));
if (!ok) throw new Error('Forbidden');
};
}