Merge pull request #739 from PicPeak/feat/admin-mfa

feat: admin two-factor authentication (TOTP) with recovery codes + CLI reset

backend/.env.example

@@ -9,6 +9,16 @@ PORT=3001
 # Generate with: openssl rand -base64 32
 JWT_SECRET=your-very-secure-jwt-secret-at-least-32-characters-long-example123456
 
+# Admin 2FA (TOTP) secret encryption key — OPTIONAL.
+# Admin authenticator secrets are encrypted at rest (AES-256-GCM). By default
+# the key is derived from JWT_SECRET, so you do NOT need to set this. Set it
+# only if you want the MFA encryption key decoupled from JWT_SECRET (e.g. so
+# rotating JWT_SECRET doesn't invalidate enrolled authenticators). If you set
+# it, changing/losing it makes existing 2FA secrets undecryptable — recover
+# with: docker compose exec backend node scripts/reset-admin-mfa.js --all --yes
+# Generate with: openssl rand -base64 32
+#MFA_ENCRYPTION_KEY=
+
 # Auth cookie Secure flag
 #   unset  - default: 'auto' in production, false in dev (#427)
 #   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access —

backend/__tests__/integration/resetAdminMfaCli.test.js

@@ -0,0 +1,82 @@
+/**
+ * CLI test for scripts/reset-admin-mfa.js — break-glass MFA reset (#738).
+ *
+ * Boots a temp-SQLite DB, seeds an admin with MFA fully enabled, then runs
+ * the script in a child process (--email <addr> --yes) pointed at the same
+ * DB file, and asserts the four MFA columns are zeroed. The script runs in
+ * its own process with its own knex connection; the parent connection is
+ * idle during the spawn so the SQLite write lock isn't contended.
+ */
+
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+jest.setTimeout(60000);
+
+let db;
+let cleanup;
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+}, 60000);
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+const SCRIPT = path.resolve(__dirname, '..', '..', 'scripts', 'reset-admin-mfa.js');
+
+async function seedEnrolledAdmin(email) {
+  const inserted = await db('admin_users').insert({
+    username: email.split('@')[0],
+    email,
+    password_hash: 'x',
+    is_active: true,
+    two_factor_enabled: true,
+    two_factor_secret: 'iv.tag.ct',
+    two_factor_recovery_codes: JSON.stringify(['$2b$10$fakehashfakehashfakehashfa']),
+    two_factor_enrolled_at: new Date(),
+    created_at: new Date(),
+  }).returning('id');
+  return inserted[0]?.id ?? inserted[0];
+}
+
+it('zeroes the four MFA columns for the targeted admin', async () => {
+  const email = '[email protected]';
+  const id = await seedEnrolledAdmin(email);
+
+  execFileSync('node', [SCRIPT, '--email', email, '--yes'], {
+    env: {
+      ...process.env,
+      NODE_ENV: 'test',
+      TEST_DATABASE_PATH: process.env.TEST_DATABASE_PATH,
+    },
+    stdio: 'pipe',
+  });
+
+  const row = await db('admin_users').where({ id }).first();
+  expect(Number(row.two_factor_enabled)).toBe(0);
+  expect(row.two_factor_secret).toBeNull();
+  expect(row.two_factor_recovery_codes).toBeNull();
+  expect(row.two_factor_enrolled_at).toBeNull();
+});
+
+it('leaves a different admin untouched', async () => {
+  const targetEmail = '[email protected]';
+  const bystanderEmail = '[email protected]';
+  const targetId = await seedEnrolledAdmin(targetEmail);
+  const bystanderId = await seedEnrolledAdmin(bystanderEmail);
+
+  execFileSync('node', [SCRIPT, '--email', targetEmail, '--yes'], {
+    env: { ...process.env, NODE_ENV: 'test', TEST_DATABASE_PATH: process.env.TEST_DATABASE_PATH },
+    stdio: 'pipe',
+  });
+
+  const target = await db('admin_users').where({ id: targetId }).first();
+  const bystander = await db('admin_users').where({ id: bystanderId }).first();
+  expect(Number(target.two_factor_enabled)).toBe(0);
+  expect(Number(bystander.two_factor_enabled)).toBe(1);
+  expect(bystander.two_factor_secret).toBe('iv.tag.ct');
+});

backend/__tests__/routes/adminMfa.test.js

@@ -0,0 +1,345 @@
+/**
+ * HTTP-level tests for the admin TOTP MFA feature (#738).
+ *
+ * Two surfaces:
+ *   1. Enrollment (adminAuth-gated) — POST /mfa/setup, /mfa/enable,
+ *      GET /mfa/status, POST /mfa/disable — mounted like server.js at
+ *      /api/admin/auth (src/routes/adminAuth.js).
+ *   2. Login challenge — POST /admin/login + POST /admin/login/mfa
+ *      (src/routes/auth.js, mounted /api/auth).
+ *
+ * Uses the same real-SQLite harness as the CRM route tests
+ * (bootCrmDb + seedMinimal + mintAdminToken). Valid TOTP codes are
+ * generated in-test via otplib's authenticator against the secret the
+ * /setup endpoint returns in plaintext.
+ *
+ * NOTE: env (TEST_DATABASE_PATH / JWT_SECRET) must be set BEFORE the
+ * first require of db.js — mirror adminCrmAuth.test.js exactly.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-adminmfa-test-'));
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
+process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'mfa-route-test-secret';
+// reCAPTCHA disabled (default) → verifyRecaptcha returns true, so login
+// tests don't need a token. Be explicit so a leaked env can't flip it on.
+delete process.env.RECAPTCHA_SECRET_KEY;
+
+const request = require('supertest');
+const bcrypt = require('bcrypt');
+const { authenticator } = require('otplib');
+
+const {
+  bootCrmDb, mintAdminToken, buildRouteApp,
+} = require('../integration/helpers/crmDb');
+
+jest.setTimeout(60000);
+
+let db;
+let cleanup;
+let adminApp; // /api/admin/auth  (enrollment)
+let authApp; // /api/auth        (login challenge)
+
+/**
+ * Seed a bare admin (password known) and return its id + login creds.
+ * seedMinimal always creates username 'tester'; we need distinct rows per
+ * scenario, so insert directly with a unique username/email.
+ */
+async function seedAdmin({ username, superAdmin = false } = {}) {
+  const password = 'correct-horse';
+  const passwordHash = await bcrypt.hash(password, 4);
+  const uname = username || `admin-${Math.random().toString(36).slice(2, 8)}`;
+  const row = {
+    username: uname,
+    email: `${uname}@example.com`,
+    password_hash: passwordHash,
+    must_change_password: false,
+    is_active: true,
+    created_at: new Date(),
+  };
+  if (superAdmin) {
+    const role = await db('roles').where({ name: 'super_admin' }).first();
+    if (!role) throw new Error('super_admin role not seeded');
+    row.role_id = role.id;
+  }
+  const inserted = await db('admin_users').insert(row).returning('id');
+  const id = inserted[0]?.id ?? inserted[0];
+  return { id, username: uname, password };
+}
+
+/** Run the full setup→enable enrollment against the live app. Returns
+ * the plaintext TOTP secret (for later login codes) and recovery codes. */
+async function enroll(adminId) {
+  const token = mintAdminToken(adminId);
+  const setup = await request(adminApp)
+    .post('/api/admin/auth/mfa/setup')
+    .set('Authorization', `Bearer ${token}`);
+  expect(setup.status).toBe(200);
+  const secret = setup.body.secret;
+
+  const enable = await request(adminApp)
+    .post('/api/admin/auth/mfa/enable')
+    .set('Authorization', `Bearer ${token}`)
+    .send({ code: authenticator.generate(secret) });
+  expect(enable.status).toBe(200);
+  return { secret, recoveryCodes: enable.body.recoveryCodes, token };
+}
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+  adminApp = buildRouteApp('/api/admin/auth', require('../../src/routes/adminAuth'));
+  authApp = buildRouteApp('/api/auth', require('../../src/routes/auth'));
+}, 60000);
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+describe('MFA enrollment — /api/admin/auth/mfa/*', () => {
+  it('setup returns a secret + otpauth URI + QR and does NOT enable yet', async () => {
+    const admin = await seedAdmin();
+    const token = mintAdminToken(admin.id);
+
+    const res = await request(adminApp)
+      .post('/api/admin/auth/mfa/setup')
+      .set('Authorization', `Bearer ${token}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.secret).toEqual(expect.any(String));
+    expect(res.body.otpauthUri).toMatch(/^otpauth:\/\/totp\//);
+    expect(res.body.qr).toMatch(/^data:image\/png;base64,/);
+
+    // Not yet enabled: status must still report disabled.
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(status.body.enabled).toBe(false);
+
+    // And the row stores an encrypted secret (not the plaintext one).
+    const row = await db('admin_users').where({ id: admin.id }).first();
+    expect(row.two_factor_secret).toBeTruthy();
+    expect(row.two_factor_secret).not.toBe(res.body.secret);
+    expect(Number(row.two_factor_enabled)).toBe(0);
+  });
+
+  it('full flow: setup → enable(valid TOTP) → status shows enabled + 10 recovery codes', async () => {
+    const admin = await seedAdmin();
+    const { recoveryCodes, token } = await enroll(admin.id);
+
+    expect(Array.isArray(recoveryCodes)).toBe(true);
+    expect(recoveryCodes).toHaveLength(10);
+
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(status.status).toBe(200);
+    expect(status.body.enabled).toBe(true);
+    expect(status.body.recoveryCodesRemaining).toBe(10);
+    expect(status.body.enrolledAt).toBeTruthy();
+  });
+
+  it('enable with a WRONG code is rejected (400) and MFA stays off', async () => {
+    const admin = await seedAdmin();
+    const token = mintAdminToken(admin.id);
+    const setup = await request(adminApp)
+      .post('/api/admin/auth/mfa/setup')
+      .set('Authorization', `Bearer ${token}`);
+    const valid = authenticator.generate(setup.body.secret);
+    const wrong = valid === '000000' ? '111111' : '000000';
+
+    const res = await request(adminApp)
+      .post('/api/admin/auth/mfa/enable')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ code: wrong });
+    expect(res.status).toBe(400);
+
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(status.body.enabled).toBe(false);
+  });
+
+  it('enable before setup is rejected', async () => {
+    const admin = await seedAdmin();
+    const token = mintAdminToken(admin.id);
+    const res = await request(adminApp)
+      .post('/api/admin/auth/mfa/enable')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ code: '123456' });
+    // No provisional secret → ValidationError (400).
+    expect(res.status).toBe(400);
+  });
+
+  it('all enrollment endpoints require a valid admin token (401 without one)', async () => {
+    const noToken = await request(adminApp).get('/api/admin/auth/mfa/status');
+    expect(noToken.status).toBe(401);
+    const setup = await request(adminApp).post('/api/admin/auth/mfa/setup');
+    expect(setup.status).toBe(401);
+  });
+
+  // Regression guard for #735: super_admin used to be blocked from enrolling.
+  // Enrollment operates on req.admin.id and is role-agnostic — assert a
+  // super_admin can complete the full setup→enable flow.
+  it('#735 regression — a super_admin can enroll in MFA', async () => {
+    const admin = await seedAdmin({ superAdmin: true });
+    const { recoveryCodes, token } = await enroll(admin.id);
+    expect(recoveryCodes).toHaveLength(10);
+
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(status.body.enabled).toBe(true);
+  });
+});
+
+describe('MFA disable — /api/admin/auth/mfa/disable', () => {
+  it('requires a valid code; a wrong code is rejected and state persists', async () => {
+    const admin = await seedAdmin();
+    const { token } = await enroll(admin.id);
+
+    const bad = await request(adminApp)
+      .post('/api/admin/auth/mfa/disable')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ code: '000000' });
+    expect(bad.status).toBe(400);
+
+    const stillOn = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(stillOn.body.enabled).toBe(true);
+  });
+
+  it('a valid TOTP disables MFA and clears the stored secret', async () => {
+    const admin = await seedAdmin();
+    const { secret, token } = await enroll(admin.id);
+
+    const res = await request(adminApp)
+      .post('/api/admin/auth/mfa/disable')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ code: authenticator.generate(secret) });
+    expect(res.status).toBe(200);
+
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${token}`);
+    expect(status.body.enabled).toBe(false);
+    expect(status.body.recoveryCodesRemaining).toBe(0);
+
+    const row = await db('admin_users').where({ id: admin.id }).first();
+    expect(row.two_factor_secret).toBeNull();
+    expect(row.two_factor_recovery_codes).toBeNull();
+  });
+});
+
+describe('Admin login challenge — /api/auth/admin/login[/mfa]', () => {
+  it('an enrolled admin gets mfaRequired + mfaToken, NO session cookie', async () => {
+    const admin = await seedAdmin();
+    await enroll(admin.id);
+
+    const res = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+
+    expect(res.status).toBe(200);
+    expect(res.body.mfaRequired).toBe(true);
+    expect(res.body.mfaToken).toEqual(expect.any(String));
+    expect(res.body.user).toBeUndefined(); // no completed session
+    // No admin auth cookie should have been set on the challenge response.
+    const cookies = res.headers['set-cookie'] || [];
+    expect(cookies.join(';')).not.toMatch(/adminToken/i);
+  });
+
+  it('a NON-enrolled admin logs in directly (no mfaRequired)', async () => {
+    const admin = await seedAdmin();
+    const res = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+    expect(res.status).toBe(200);
+    expect(res.body.mfaRequired).toBeUndefined();
+    expect(res.body.user).toBeDefined();
+    expect(res.body.user.username).toBe(admin.username);
+  });
+
+  it('login/mfa with a valid TOTP completes the session', async () => {
+    const admin = await seedAdmin();
+    const { secret } = await enroll(admin.id);
+
+    const challenge = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+    const { mfaToken } = challenge.body;
+
+    const res = await request(authApp)
+      .post('/api/auth/admin/login/mfa')
+      .send({ mfaToken, code: authenticator.generate(secret) });
+
+    expect(res.status).toBe(200);
+    expect(res.body.user).toBeDefined();
+    expect(res.body.user.id).toBe(admin.id);
+  });
+
+  it('login/mfa with a wrong code is 401 MFA_INVALID', async () => {
+    const admin = await seedAdmin();
+    const { secret } = await enroll(admin.id);
+    const challenge = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+
+    const valid = authenticator.generate(secret);
+    const wrong = valid === '000000' ? '111111' : '000000';
+    const res = await request(authApp)
+      .post('/api/auth/admin/login/mfa')
+      .send({ mfaToken: challenge.body.mfaToken, code: wrong });
+
+    expect(res.status).toBe(401);
+    expect(res.body.code).toBe('MFA_INVALID');
+    expect(res.body.user).toBeUndefined();
+  });
+
+  it('a recovery code logs in and is then single-use (second use fails)', async () => {
+    const admin = await seedAdmin();
+    const { recoveryCodes } = await enroll(admin.id);
+    const recovery = recoveryCodes[0];
+
+    // First challenge + recovery-code exchange succeeds.
+    const c1 = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+    const first = await request(authApp)
+      .post('/api/auth/admin/login/mfa')
+      .send({ mfaToken: c1.body.mfaToken, code: recovery });
+    expect(first.status).toBe(200);
+    expect(first.body.user).toBeDefined();
+
+    // recoveryCodesRemaining dropped by one.
+    const status = await request(adminApp)
+      .get('/api/admin/auth/mfa/status')
+      .set('Authorization', `Bearer ${mintAdminToken(admin.id)}`);
+    expect(status.body.recoveryCodesRemaining).toBe(9);
+
+    // Second use of the SAME recovery code must fail.
+    const c2 = await request(authApp)
+      .post('/api/auth/admin/login')
+      .send({ username: admin.username, password: admin.password });
+    const second = await request(authApp)
+      .post('/api/auth/admin/login/mfa')
+      .send({ mfaToken: c2.body.mfaToken, code: recovery });
+    expect(second.status).toBe(401);
+    expect(second.body.code).toBe('MFA_INVALID');
+  });
+
+  it('login/mfa rejects a non-mfa_pending token (e.g. a normal admin JWT)', async () => {
+    const admin = await seedAdmin();
+    await enroll(admin.id);
+    const res = await request(authApp)
+      .post('/api/auth/admin/login/mfa')
+      .send({ mfaToken: mintAdminToken(admin.id), code: '123456' });
+    expect(res.status).toBe(401);
+  });
+});

backend/__tests__/services/mfaService.test.js

@@ -0,0 +1,193 @@
+/**
+ * Unit tests for mfaService — admin TOTP MFA (#738).
+ *
+ * Pure unit: no DB, no Express. Exercises the crypto/verification surface
+ * directly. JWT_SECRET is set at the top so getEncryptionKey()'s scrypt
+ * derivation has key material (the service derives the AES key from
+ * MFA_ENCRYPTION_KEY, falling back to JWT_SECRET).
+ */
+
+// Must be set BEFORE the service is required — the key is derived lazily per
+// call, but keep it explicit and stable so encrypt/decrypt round-trips.
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'mfa-unit-test-secret';
+delete process.env.MFA_ENCRYPTION_KEY; // ensure we derive from JWT_SECRET
+
+const { authenticator } = require('otplib');
+const mfaService = require('../../src/services/mfaService');
+
+describe('mfaService — secret encryption (AES-256-GCM)', () => {
+  it('round-trips encrypt → decrypt to the original secret', () => {
+    const secret = mfaService.generateSecret();
+    const blob = mfaService.encryptSecret(secret);
+    expect(blob).toEqual(expect.any(String));
+    expect(blob).not.toContain(secret); // stored form is not plaintext
+    expect(blob.split('.')).toHaveLength(3); // iv.tag.ciphertext
+    expect(mfaService.decryptSecret(blob)).toBe(secret);
+  });
+
+  it('produces a different ciphertext each time (random IV) but decrypts identically', () => {
+    const secret = mfaService.generateSecret();
+    const a = mfaService.encryptSecret(secret);
+    const b = mfaService.encryptSecret(secret);
+    expect(a).not.toBe(b);
+    expect(mfaService.decryptSecret(a)).toBe(secret);
+    expect(mfaService.decryptSecret(b)).toBe(secret);
+  });
+
+  it('throws when decrypting a malformed blob (wrong segment count)', () => {
+    expect(() => mfaService.decryptSecret('garbage')).toThrow();
+    expect(() => mfaService.decryptSecret('only.two')).toThrow();
+  });
+
+  it('throws when the auth tag / ciphertext is tampered with', () => {
+    const secret = mfaService.generateSecret();
+    const [iv, tag, ct] = mfaService.encryptSecret(secret).split('.');
+    // Flip a character in the ciphertext → GCM auth check must fail.
+    const tampered = ct.slice(0, -2) + (ct.slice(-2) === 'AA' ? 'BB' : 'AA');
+    expect(() => mfaService.decryptSecret([iv, tag, tampered].join('.'))).toThrow();
+  });
+});
+
+describe('mfaService — TOTP verification', () => {
+  it('accepts a freshly generated code for the plaintext secret', () => {
+    const secret = mfaService.generateSecret();
+    const code = authenticator.generate(secret);
+    expect(mfaService.verifyTotp(code, secret)).toBe(true);
+  });
+
+  it('tolerates whitespace in the submitted code', () => {
+    const secret = mfaService.generateSecret();
+    const code = authenticator.generate(secret);
+    expect(mfaService.verifyTotp(` ${code} `, secret)).toBe(true);
+  });
+
+  it('rejects a wrong code', () => {
+    const secret = mfaService.generateSecret();
+    const code = authenticator.generate(secret);
+    const wrong = code === '000000' ? '111111' : '000000';
+    expect(mfaService.verifyTotp(wrong, secret)).toBe(false);
+  });
+
+  it('returns false for empty inputs rather than throwing', () => {
+    const secret = mfaService.generateSecret();
+    expect(mfaService.verifyTotp('', secret)).toBe(false);
+    expect(mfaService.verifyTotp('123456', '')).toBe(false);
+    expect(mfaService.verifyTotp(null, secret)).toBe(false);
+  });
+
+  it('verifies through the encrypted blob (verifyTotpEncrypted)', () => {
+    const secret = mfaService.generateSecret();
+    const stored = mfaService.encryptSecret(secret);
+    const code = authenticator.generate(secret);
+    expect(mfaService.verifyTotpEncrypted(code, stored)).toBe(true);
+
+    const wrong = code === '000000' ? '111111' : '000000';
+    expect(mfaService.verifyTotpEncrypted(wrong, stored)).toBe(false);
+  });
+
+  it('verifyTotpEncrypted returns false (no throw) for a corrupt blob', () => {
+    const secret = mfaService.generateSecret();
+    const code = authenticator.generate(secret);
+    expect(mfaService.verifyTotpEncrypted(code, 'not-a-valid-blob')).toBe(false);
+  });
+});
+
+describe('mfaService — otpauth URI / QR', () => {
+  it('builds an otpauth:// URI containing issuer, account and secret', () => {
+    const secret = mfaService.generateSecret();
+    const uri = mfaService.buildOtpauthUri('[email protected]', secret);
+    expect(uri).toMatch(/^otpauth:\/\/totp\//);
+    expect(uri).toContain(encodeURIComponent(mfaService.ISSUER));
+    expect(uri).toContain(`secret=${secret}`);
+  });
+
+  it('builds a PNG data-URL QR for the URI', async () => {
+    const secret = mfaService.generateSecret();
+    const uri = mfaService.buildOtpauthUri('[email protected]', secret);
+    const qr = await mfaService.buildQrDataUrl(uri);
+    expect(qr).toMatch(/^data:image\/png;base64,/);
+  });
+});
+
+describe('mfaService — recovery codes', () => {
+  it('generates 10 distinct plaintext codes and 10 distinct hashes', async () => {
+    const { plain, hashed } = await mfaService.generateRecoveryCodes();
+    expect(plain).toHaveLength(mfaService.RECOVERY_CODE_COUNT);
+    expect(hashed).toHaveLength(mfaService.RECOVERY_CODE_COUNT);
+    expect(new Set(plain).size).toBe(10);
+    expect(new Set(hashed).size).toBe(10);
+    // Hashes are bcrypt, not the plaintext.
+    hashed.forEach((h) => expect(h).toMatch(/^\$2[aby]\$/));
+    plain.forEach((p) => expect(hashed).not.toContain(p));
+  });
+
+  it('formats a raw code into 4-char groups', () => {
+    expect(mfaService.formatRecoveryCode('abcdefghij')).toBe('abcd-efgh-ij');
+  });
+
+  it('consumes a valid recovery code once and removes it (single-use)', async () => {
+    const { plain, hashed } = await mfaService.generateRecoveryCodes();
+    const target = plain[3];
+
+    const first = await mfaService.consumeRecoveryCode(target, hashed);
+    expect(first.matched).toBe(true);
+    expect(first.remainingHashes).toHaveLength(9);
+
+    // Reusing the same code against the reduced set must now fail.
+    const reuse = await mfaService.consumeRecoveryCode(target, first.remainingHashes);
+    expect(reuse.matched).toBe(false);
+    expect(reuse.remainingHashes).toHaveLength(9);
+  });
+
+  it('matches case-insensitively and trims whitespace', async () => {
+    const { plain, hashed } = await mfaService.generateRecoveryCodes();
+    const res = await mfaService.consumeRecoveryCode(`  ${plain[0].toUpperCase()}  `, hashed);
+    expect(res.matched).toBe(true);
+  });
+
+  it('rejects a wrong code and leaves the hash set unchanged', async () => {
+    const { hashed } = await mfaService.generateRecoveryCodes();
+    const res = await mfaService.consumeRecoveryCode('zzzz-zzzz-zz', hashed);
+    expect(res.matched).toBe(false);
+    expect(res.remainingHashes).toHaveLength(10);
+  });
+
+  it('handles empty / missing input safely', async () => {
+    const { hashed } = await mfaService.generateRecoveryCodes();
+    const res = await mfaService.consumeRecoveryCode('', hashed);
+    expect(res.matched).toBe(false);
+    expect(res.remainingHashes).toBe(hashed);
+    const noHashes = await mfaService.consumeRecoveryCode('abcd-efgh-ij', null);
+    expect(noHashes.matched).toBe(false);
+    expect(noHashes.remainingHashes).toEqual([]);
+  });
+});
+
+describe('mfaService — parseRecoveryCodes', () => {
+  it('parses a JSON string array', () => {
+    expect(mfaService.parseRecoveryCodes(JSON.stringify(['a', 'b']))).toEqual(['a', 'b']);
+  });
+  it('passes an already-array through', () => {
+    expect(mfaService.parseRecoveryCodes(['a', 'b'])).toEqual(['a', 'b']);
+  });
+  it('returns [] for null / garbage / non-array JSON', () => {
+    expect(mfaService.parseRecoveryCodes(null)).toEqual([]);
+    expect(mfaService.parseRecoveryCodes('{not json')).toEqual([]);
+    expect(mfaService.parseRecoveryCodes(JSON.stringify({ a: 1 }))).toEqual([]);
+  });
+});
+
+describe('mfaService — isEnrolled coercion', () => {
+  it('treats true / 1 / "1" as enrolled', () => {
+    expect(mfaService.isEnrolled({ two_factor_enabled: true })).toBe(true);
+    expect(mfaService.isEnrolled({ two_factor_enabled: 1 })).toBe(true);
+    expect(mfaService.isEnrolled({ two_factor_enabled: '1' })).toBe(true);
+  });
+  it('treats false / 0 / null / missing as not enrolled', () => {
+    expect(mfaService.isEnrolled({ two_factor_enabled: false })).toBe(false);
+    expect(mfaService.isEnrolled({ two_factor_enabled: 0 })).toBe(false);
+    expect(mfaService.isEnrolled({ two_factor_enabled: null })).toBe(false);
+    expect(mfaService.isEnrolled({})).toBe(false);
+    expect(mfaService.isEnrolled(null)).toBe(false);
+  });
+});

backend/migrations/core/151_add_admin_mfa_recovery.js

@@ -0,0 +1,58 @@
+/**
+ * Migration 151: admin MFA (TOTP) enrollment support — issue #738.
+ *
+ * The `admin_users.two_factor_enabled` / `two_factor_secret` columns already
+ * exist from the legacy migration 016 but were never wired to any code. This
+ * migration adds the two columns the real TOTP flow needs on top of them:
+ *
+ *   - two_factor_recovery_codes: JSON array of one-time backup codes, stored
+ *     HASHED (never plaintext), so a locked-out admin can log in without the
+ *     authenticator. Consumed on use.
+ *   - two_factor_enrolled_at: when the admin completed enrollment (audit /
+ *     display only).
+ *
+ * The TOTP secret itself continues to live in the existing `two_factor_secret`
+ * column, but is now stored ENCRYPTED at rest (AES-256-GCM) by mfaService —
+ * the column type is unchanged (the encrypted blob is short).
+ *
+ * Additive and idempotent: only adds columns, guarded by hasColumn, so it is
+ * safe to re-run and touches no existing data.
+ */
+exports.up = async function (knex) {
+  const hasRecovery = await knex.schema.hasColumn('admin_users', 'two_factor_recovery_codes');
+  const hasEnrolledAt = await knex.schema.hasColumn('admin_users', 'two_factor_enrolled_at');
+  const hasEnabled = await knex.schema.hasColumn('admin_users', 'two_factor_enabled');
+  const hasSecret = await knex.schema.hasColumn('admin_users', 'two_factor_secret');
+
+  await knex.schema.alterTable('admin_users', (t) => {
+    // Backfill the legacy columns too, in case an install somehow lacks them
+    // (016 is a legacy migration; guard defensively).
+    if (!hasEnabled) {
+      t.boolean('two_factor_enabled').defaultTo(false);
+    }
+    if (!hasSecret) {
+      t.string('two_factor_secret').nullable();
+    }
+    if (!hasRecovery) {
+      t.text('two_factor_recovery_codes').nullable();
+    }
+    if (!hasEnrolledAt) {
+      t.timestamp('two_factor_enrolled_at').nullable();
+    }
+  });
+};
+
+exports.down = async function (knex) {
+  const hasRecovery = await knex.schema.hasColumn('admin_users', 'two_factor_recovery_codes');
+  const hasEnrolledAt = await knex.schema.hasColumn('admin_users', 'two_factor_enrolled_at');
+
+  await knex.schema.alterTable('admin_users', (t) => {
+    // Only drop what THIS migration added; leave the legacy 016 columns.
+    if (hasRecovery) {
+      t.dropColumn('two_factor_recovery_codes');
+    }
+    if (hasEnrolledAt) {
+      t.dropColumn('two_factor_enrolled_at');
+    }
+  });
+};

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "picpeak-backend",
-  "version": "3.74.0-beta.0",
+  "version": "3.80.0-beta.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "picpeak-backend",
-      "version": "3.74.0-beta.0",
+      "version": "3.80.0-beta.0",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.850.0",
         "@aws-sdk/lib-storage": "^3.850.0",
@@ -40,6 +40,7 @@
         "node-cron": "^3.0.2",
         "node-stream-zip": "^1.15.0",
         "nodemailer": "^9.0.1",
+        "otplib": "^12.0.1",
         "pdf-lib": "^1.17.1",
         "pdfkit": "^0.17.2",
         "pg": "^8.16.3",
@@ -2703,6 +2704,56 @@
         "node": ">=10"
       }
     },
+    "node_modules/@otplib/core": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/@otplib/core/-/core-12.0.1.tgz",
+      "integrity": "sha512-4sGntwbA/AC+SbPhbsziRiD+jNDdIzsZ3JUyfZwjtKyc/wufl1pnSIaG4Uqx8ymPagujub0o92kgBnB89cuAMA==",
+      "license": "MIT"
+    },
+    "node_modules/@otplib/plugin-crypto": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/@otplib/plugin-crypto/-/plugin-crypto-12.0.1.tgz",
+      "integrity": "sha512-qPuhN3QrT7ZZLcLCyKOSNhuijUi9G5guMRVrxq63r9YNOxxQjPm59gVxLM+7xGnHnM6cimY57tuKsjK7y9LM1g==",
+      "deprecated": "Please upgrade to v13 of otplib. Refer to otplib docs for migration paths",
+      "license": "MIT",
+      "dependencies": {
+        "@otplib/core": "^12.0.1"
+      }
+    },
+    "node_modules/@otplib/plugin-thirty-two": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/@otplib/plugin-thirty-two/-/plugin-thirty-two-12.0.1.tgz",
+      "integrity": "sha512-MtT+uqRso909UkbrrYpJ6XFjj9D+x2Py7KjTO9JDPhL0bJUYVu5kFP4TFZW4NFAywrAtFRxOVY261u0qwb93gA==",
+      "deprecated": "Please upgrade to v13 of otplib. Refer to otplib docs for migration paths",
+      "license": "MIT",
+      "dependencies": {
+        "@otplib/core": "^12.0.1",
+        "thirty-two": "^1.0.2"
+      }
+    },
+    "node_modules/@otplib/preset-default": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/@otplib/preset-default/-/preset-default-12.0.1.tgz",
+      "integrity": "sha512-xf1v9oOJRyXfluBhMdpOkr+bsE+Irt+0D5uHtvg6x1eosfmHCsCC6ej/m7FXiWqdo0+ZUI6xSKDhJwc8yfiOPQ==",
+      "deprecated": "Please upgrade to v13 of otplib. Refer to otplib docs for migration paths",
+      "license": "MIT",
+      "dependencies": {
+        "@otplib/core": "^12.0.1",
+        "@otplib/plugin-crypto": "^12.0.1",
+        "@otplib/plugin-thirty-two": "^12.0.1"
+      }
+    },
+    "node_modules/@otplib/preset-v11": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/@otplib/preset-v11/-/preset-v11-12.0.1.tgz",
+      "integrity": "sha512-9hSetMI7ECqbFiKICrNa4w70deTUfArtwXykPUvSHWOdzOlfa9ajglu7mNCntlvxycTiOAXkQGwjQCzzDEMRMg==",
+      "license": "MIT",
+      "dependencies": {
+        "@otplib/core": "^12.0.1",
+        "@otplib/plugin-crypto": "^12.0.1",
+        "@otplib/plugin-thirty-two": "^12.0.1"
+      }
+    },
     "node_modules/@paralleldrive/cuid2": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
@@ -9371,6 +9422,17 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/otplib": {
+      "version": "12.0.1",
+      "resolved": "https://registry.npmjs.org/otplib/-/otplib-12.0.1.tgz",
+      "integrity": "sha512-xDGvUOQjop7RDgxTQ+o4pOol0/3xSZzawTiPKRrHnQWAy0WjhNs/5HdIDJCrqC4MBynmjXgULc6YfioaxZeFgg==",
+      "license": "MIT",
+      "dependencies": {
+        "@otplib/core": "^12.0.1",
+        "@otplib/preset-default": "^12.0.1",
+        "@otplib/preset-v11": "^12.0.1"
+      }
+    },
     "node_modules/p-limit": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
@@ -11668,6 +11730,14 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/thirty-two": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/thirty-two/-/thirty-two-1.0.2.tgz",
+      "integrity": "sha512-OEI0IWCe+Dw46019YLl6V10Us5bi574EvlJEOcAkB29IzQ/mYD1A6RyNHLjZPiHCmuodxvgF6U+vZO1L15lxVA==",
+      "engines": {
+        "node": ">=0.2.6"
+      }
+    },
     "node_modules/thread-stream": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.2.0.tgz",

backend/package.json

@@ -46,9 +46,11 @@
     "node-cron": "^3.0.2",
     "node-stream-zip": "^1.15.0",
     "nodemailer": "^9.0.1",
+    "otplib": "^12.0.1",
     "pdf-lib": "^1.17.1",
     "pdfkit": "^0.17.2",
     "pg": "^8.16.3",
+    "postcss": "8.5.10",
     "qrcode": "^1.5.4",
     "react-i18next": "^15.6.0",
     "sanitize-html": "^2.17.0",
@@ -57,11 +59,10 @@
     "swagger-jsdoc": "^6.2.8",
     "swagger-ui-express": "^5.0.1",
     "swissqrbill": "^4.3.0",
+    "tar": ">=7.5.16",
     "uuid": "^11.1.1",
     "winston": "^3.8.2",
-    "zxcvbn": "^4.4.2",
-    "postcss": "8.5.10",
-    "tar": ">=7.5.16"
+    "zxcvbn": "^4.4.2"
   },
   "devDependencies": {
     "eslint": "^8.40.0",

backend/scripts/reset-admin-mfa.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * reset-admin-mfa.js — disable two-factor auth for a locked-out admin (#738).
+ *
+ * Break-glass recovery for when an admin loses their authenticator AND their
+ * recovery codes. Clears the MFA state so the admin can log in with just their
+ * password and re-enroll from Settings.
+ *
+ * Usage (inside the running backend container):
+ *   docker compose exec backend node scripts/reset-admin-mfa.js --email [email protected]
+ *   docker compose exec backend node scripts/reset-admin-mfa.js --all --yes
+ *
+ * Flags:
+ *   --email <addr>   target a single admin by email (or --username <name>)
+ *   --all            reset MFA for EVERY admin (full lockout / break-glass)
+ *   --yes            non-interactive (skip the confirmation prompt)
+ */
+
+const readline = require('readline');
+const { db, logActivity } = require('../src/database/db');
+
+const args = process.argv.slice(2);
+const hasFlag = (f) => args.includes(f);
+const getOption = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 && i + 1 < args.length ? args[i + 1] : null;
+};
+
+const force = hasFlag('--yes') || hasFlag('--force') || hasFlag('--non-interactive');
+const all = hasFlag('--all');
+const email = getOption('email');
+const username = getOption('username');
+
+const MFA_CLEAR = {
+  two_factor_enabled: false,
+  two_factor_secret: null,
+  two_factor_recovery_codes: null,
+  two_factor_enrolled_at: null,
+  updated_at: new Date(),
+};
+
+function ask(prompt) {
+  if (force) return Promise.resolve('yes');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(prompt, (a) => { rl.close(); resolve(a); }));
+}
+
+async function main() {
+  console.log('\n========================================');
+  console.log('PicPeak Admin MFA Reset Tool');
+  console.log('========================================\n');
+
+  if (!all && !email && !username) {
+    console.error('❌ Specify a target: --email <addr>, --username <name>, or --all');
+    console.log('   e.g. node scripts/reset-admin-mfa.js --email [email protected]');
+    process.exit(1);
+  }
+
+  // Resolve target admins.
+  let targets;
+  if (all) {
+    targets = await db('admin_users').select('id', 'username', 'email', 'two_factor_enabled');
+  } else {
+    const q = db('admin_users');
+    if (email) q.where({ email });
+    if (username) q.where({ username });
+    targets = await q.select('id', 'username', 'email', 'two_factor_enabled');
+  }
+
+  if (targets.length === 0) {
+    console.error('❌ No matching admin user found.');
+    process.exit(1);
+  }
+
+  const enrolled = targets.filter((t) => t.two_factor_enabled === true || t.two_factor_enabled === 1);
+  console.log(`Matched ${targets.length} admin(s); ${enrolled.length} currently have MFA enabled:`);
+  for (const t of targets) {
+    const flag = (t.two_factor_enabled === true || t.two_factor_enabled === 1) ? 'MFA ON' : 'mfa off';
+    console.log(`  - ${t.username} <${t.email}>  [${flag}]`);
+  }
+
+  const confirm = await ask('\nDisable MFA for the above? (yes/no): ');
+  const normalized = String(confirm).trim().toLowerCase();
+  if (normalized !== 'yes' && normalized !== 'y') {
+    console.log('\n❌ Cancelled. No changes made.');
+    process.exit(0);
+  }
+
+  const ids = targets.map((t) => t.id);
+  const updated = await db('admin_users').whereIn('id', ids).update(MFA_CLEAR);
+
+  for (const t of targets) {
+    try {
+      await logActivity('admin_mfa_reset_cli',
+        { admin_id: t.id, via: 'cli' },
+        null,
+        { type: 'system', id: 0, name: 'reset-admin-mfa.js' }
+      );
+    } catch (_) { /* activity log is best-effort */ }
+  }
+
+  console.log(`\n✅ MFA disabled for ${updated} admin(s). They can now log in with just their password and re-enroll from Settings → Security.`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('❌ Failed to reset MFA:', err.message);
+  process.exit(1);
+});

backend/src/routes/adminAuth.js

@@ -10,6 +10,7 @@ const { handleAsync, validateRequest, successResponse } = require('../utils/rout
 const { NotFoundError, ConflictError, ValidationError } = require('../utils/errors');
 const { setAdminAuthCookie } = require('../utils/tokenUtils');
 const { IDENTITY_PRESERVING_NORMALIZE_EMAIL } = require('../utils/emailNormalization');
+const mfaService = require('../services/mfaService');
 const router = express.Router();
 
 // Get admin profile
@@ -184,4 +185,175 @@ router.post('/logout', adminAuth, handleAsync(async (req, res) => {
   successResponse(res, { message: 'Logged out successfully' });
 }));
 
+// ---------------------------------------------------------------------------
+// Multi-factor authentication (TOTP) — issue #738.
+//
+// All endpoints operate on the AUTHENTICATED admin's own account
+// (req.admin.id) — enrollment is per-user and works for every role,
+// super_admin included (closes #735). The TOTP secret is stored encrypted
+// at rest and recovery codes are hashed; see services/mfaService.js.
+// ---------------------------------------------------------------------------
+
+const isMfaEnabled = mfaService.isEnrolled;
+
+// Current MFA state for the logged-in admin.
+router.get('/mfa/status', adminAuth, handleAsync(async (req, res) => {
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  const enabled = isMfaEnabled(admin);
+  res.json({
+    enabled,
+    enrolledAt: enabled ? admin.two_factor_enrolled_at || null : null,
+    recoveryCodesRemaining: enabled
+      ? mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes).length
+      : 0
+  });
+}));
+
+// Begin enrollment: mint a provisional secret, store it encrypted (NOT yet
+// enabled), and return the otpauth URI + QR for the authenticator app. Calling
+// this again before /enable simply regenerates the provisional secret.
+router.post('/mfa/setup', adminAuth, handleAsync(async (req, res) => {
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (isMfaEnabled(admin)) {
+    throw new ConflictError('Two-factor authentication is already enabled');
+  }
+
+  const secret = mfaService.generateSecret();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_secret: mfaService.encryptSecret(secret),
+    two_factor_enabled: false,
+    two_factor_recovery_codes: null,
+    two_factor_enrolled_at: null,
+    updated_at: new Date()
+  });
+
+  const accountName = admin.email || admin.username;
+  const otpauthUri = mfaService.buildOtpauthUri(accountName, secret);
+  const qr = await mfaService.buildQrDataUrl(otpauthUri);
+
+  res.json({
+    // `secret` is returned for manual entry when a QR can't be scanned.
+    secret,
+    otpauthUri,
+    qr,
+    issuer: mfaService.ISSUER,
+    account: accountName
+  });
+}));
+
+// Complete enrollment: verify a code against the provisional secret, enable
+// MFA, and return one-time recovery codes (shown exactly once).
+router.post('/mfa/enable', [
+  adminAuth,
+  body('code').notEmpty().withMessage('Verification code is required')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (isMfaEnabled(admin)) {
+    throw new ConflictError('Two-factor authentication is already enabled');
+  }
+  if (!admin.two_factor_secret) {
+    throw new ValidationError('Start setup before enabling two-factor authentication');
+  }
+  if (!mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret)) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  const { plain, hashed } = await mfaService.generateRecoveryCodes();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_enabled: true,
+    two_factor_enrolled_at: new Date(),
+    two_factor_recovery_codes: JSON.stringify(hashed),
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_enabled',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, {
+    message: 'Two-factor authentication enabled',
+    recoveryCodes: plain
+  });
+}));
+
+// Disable MFA. Requires a fresh TOTP or recovery code so a hijacked session
+// can't silently strip the second factor.
+router.post('/mfa/disable', [
+  adminAuth,
+  body('code').notEmpty().withMessage('A current code is required to disable 2FA')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (!isMfaEnabled(admin)) {
+    throw new ValidationError('Two-factor authentication is not enabled');
+  }
+
+  const totpOk = mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret);
+  let recoveryOk = false;
+  if (!totpOk) {
+    const stored = mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes);
+    recoveryOk = (await mfaService.consumeRecoveryCode(req.body.code, stored)).matched;
+  }
+  if (!totpOk && !recoveryOk) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_enabled: false,
+    two_factor_secret: null,
+    two_factor_recovery_codes: null,
+    two_factor_enrolled_at: null,
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_disabled',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, { message: 'Two-factor authentication disabled' });
+}));
+
+// Regenerate recovery codes (invalidates the old set). Requires a fresh TOTP
+// code. Returns the new codes once.
+router.post('/mfa/recovery-codes', [
+  adminAuth,
+  body('code').notEmpty().withMessage('A current authenticator code is required')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (!isMfaEnabled(admin)) {
+    throw new ValidationError('Two-factor authentication is not enabled');
+  }
+  if (!mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret)) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  const { plain, hashed } = await mfaService.generateRecoveryCodes();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_recovery_codes: JSON.stringify(hashed),
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_recovery_regenerated',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, {
+    message: 'Recovery codes regenerated',
+    recoveryCodes: plain
+  });
+}));
+
 module.exports = router;

backend/src/routes/auth.js

@@ -2,9 +2,10 @@ const express = require('express');
 const bcrypt = require('bcrypt');
 const jwt = require('jsonwebtoken');
 const { body, validationResult } = require('express-validator');
-const { db } = require('../database/db');
+const { db, logActivity } = require('../database/db');
 const { formatBoolean } = require('../utils/dbCompat');
 const { verifyRecaptcha } = require('../services/recaptcha');
+const mfaService = require('../services/mfaService');
 const { 
   trackFailedAttempt,
   trackSuccessfulLogin,
@@ -33,6 +34,49 @@ const {
 } = require('../utils/passwordValidation');
 const router = express.Router();
 
+/**
+ * Finish a successful admin login: reset the lockout counter, stamp
+ * last_login, mint the 24h admin JWT, set the HttpOnly cookie, and return the
+ * user payload. Shared by the direct (no-MFA) path and the MFA-verify path so
+ * both produce an identical session. `lockoutKey` is the identifier the user
+ * typed (username or email) so success/failure tracking stays in one bucket.
+ */
+async function completeAdminLogin(req, res, admin, ipAddress, userAgent, lockoutKey) {
+  await trackSuccessfulLogin(lockoutKey, ipAddress, userAgent);
+
+  await db('admin_users').where('id', admin.id).update({
+    last_login: new Date(),
+    last_login_ip: ipAddress
+  });
+
+  const token = jwt.sign({
+    id: admin.id,
+    username: admin.username,
+    type: 'admin',
+    role: admin.role_name,
+    ip: ipAddress,
+    loginTime: Date.now()
+  }, process.env.JWT_SECRET, {
+    expiresIn: '24h',
+    issuer: 'picpeak-auth'
+  });
+
+  setAdminAuthCookie(res, token);
+
+  return res.json({
+    user: {
+      id: admin.id,
+      username: admin.username,
+      email: admin.email,
+      mustChangePassword: admin.must_change_password || false,
+      role: admin.role_name ? {
+        name: admin.role_name,
+        displayName: admin.role_display_name
+      } : null
+    }
+  });
+}
+
 // Admin login with enhanced security
 router.post('/admin/login', [
   body('username').notEmpty().trim(),
@@ -95,49 +139,132 @@ router.post('/admin/login', [
       return res.status(401).json({ error: getGenericAuthError() });
     }
 
-    // Successful login
-    await trackSuccessfulLogin(username, ipAddress, userAgent);
-
-    // Update last login and login metadata
-    await db('admin_users').where('id', admin.id).update({
-      last_login: new Date(),
-      last_login_ip: ipAddress
-    });
-
-    // Generate token with additional claims including role
-    const token = jwt.sign({
-      id: admin.id,
-      username: admin.username,
-      type: 'admin',
-      role: admin.role_name, // Add role to JWT
-      ip: ipAddress,
-      loginTime: Date.now()
-    }, process.env.JWT_SECRET, {
-      expiresIn: '24h',
-      issuer: 'picpeak-auth'
-    });
-
-    setAdminAuthCookie(res, token);
-
-    // Token is delivered via HttpOnly cookie only (not in response body)
-    res.json({
-      user: {
+    // Second factor: if this admin has TOTP enabled, do NOT complete the login
+    // yet. Issue a short-lived, single-purpose mfa_pending token and require the
+    // code via /admin/login/mfa. We deliberately don't reset the lockout counter
+    // (trackSuccessfulLogin) or stamp last_login until the second factor passes,
+    // so MFA brute-force is still gated by the account lockout. `loginId` carries
+    // the typed identifier so the verify step tracks the same lockout bucket.
+    if (mfaService.isEnrolled(admin)) {
+      const mfaToken = jwt.sign({
         id: admin.id,
         username: admin.username,
-        email: admin.email,
-        mustChangePassword: admin.must_change_password || false,
-        role: admin.role_name ? {
-          name: admin.role_name,
-          displayName: admin.role_display_name
-        } : null
-      }
-    });
+        type: 'mfa_pending',
+        loginId: username
+      }, process.env.JWT_SECRET, {
+        expiresIn: '5m',
+        issuer: 'picpeak-auth'
+      });
+      return res.json({ mfaRequired: true, mfaToken });
+    }
+
+    return await completeAdminLogin(req, res, admin, ipAddress, userAgent, username);
   } catch (error) {
     logger.error('Login error:', error);
     res.status(500).json({ error: 'Login failed' });
   }
 });
 
+// Second-factor verification. Exchanges the short-lived mfa_pending token
+// (from /admin/login) plus a TOTP or recovery code for a full admin session.
+router.post('/admin/login/mfa', [
+  body('mfaToken').notEmpty(),
+  body('code').notEmpty().trim()
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { mfaToken, code } = req.body;
+    const ipAddress = getClientIp(req);
+    const userAgent = req.headers['user-agent'] || '';
+
+    let decoded;
+    try {
+      decoded = jwt.verify(mfaToken, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
+        issuer: 'picpeak-auth'
+      });
+    } catch (err) {
+      return res.status(401).json({
+        error: 'Your verification session expired. Please sign in again.',
+        code: 'MFA_SESSION_EXPIRED'
+      });
+    }
+
+    if (decoded.type !== 'mfa_pending') {
+      return res.status(401).json({ error: getGenericAuthError() });
+    }
+
+    const lockoutKey = decoded.loginId || decoded.username;
+    const lockoutStatus = await checkAccountLockout(lockoutKey);
+    if (lockoutStatus.isLocked) {
+      return res.status(423).json({
+        error: 'Account temporarily locked due to too many failed attempts',
+        retryAfter: lockoutStatus.remainingTime
+      });
+    }
+
+    const admin = await db('admin_users')
+      .leftJoin('roles', 'roles.id', 'admin_users.role_id')
+      .where('admin_users.id', decoded.id)
+      .select(
+        'admin_users.*',
+        'roles.name as role_name',
+        'roles.display_name as role_display_name'
+      )
+      .first();
+
+    if (!admin || !admin.is_active || !mfaService.isEnrolled(admin)) {
+      return res.status(401).json({ error: getGenericAuthError() });
+    }
+
+    // TOTP first, then a one-time recovery code.
+    let ok = mfaService.verifyTotpEncrypted(code, admin.two_factor_secret);
+    let usedRecovery = false;
+    let remainingHashes = null;
+    if (!ok) {
+      const stored = mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes);
+      const result = await mfaService.consumeRecoveryCode(code, stored);
+      if (result.matched) {
+        ok = true;
+        usedRecovery = true;
+        remainingHashes = result.remainingHashes;
+      }
+    }
+
+    if (!ok) {
+      await trackFailedAttempt(lockoutKey, ipAddress, userAgent);
+      return res.status(401).json({ error: 'Invalid verification code', code: 'MFA_INVALID' });
+    }
+
+    if (usedRecovery) {
+      await db('admin_users').where('id', admin.id).update({
+        two_factor_recovery_codes: JSON.stringify(remainingHashes),
+        updated_at: new Date()
+      });
+      await logActivity('admin_mfa_recovery_used',
+        { admin_id: admin.id, remaining: remainingHashes.length },
+        null,
+        { type: 'admin', id: admin.id, name: admin.username }
+      );
+    }
+
+    await logActivity('admin_mfa_login',
+      { admin_id: admin.id, method: usedRecovery ? 'recovery_code' : 'totp' },
+      null,
+      { type: 'admin', id: admin.id, name: admin.username }
+    );
+
+    return await completeAdminLogin(req, res, admin, ipAddress, userAgent, lockoutKey);
+  } catch (error) {
+    logger.error('MFA verification error:', error);
+    res.status(500).json({ error: 'Verification failed' });
+  }
+});
+
 // Logout endpoint
 router.post('/logout', async (req, res) => {
   try {

backend/src/services/mfaService.js

@@ -0,0 +1,183 @@
+/**
+ * mfaService — TOTP (RFC 6238) multi-factor auth for admin accounts (#738).
+ *
+ * Responsibilities:
+ *   - generate/verify TOTP secrets (otplib, standard SHA1/6-digit/30s so
+ *     Google Authenticator / Authy / 1Password all work);
+ *   - encrypt the secret at rest (AES-256-GCM) so a DB leak alone doesn't
+ *     yield working authenticator seeds;
+ *   - generate/verify one-time recovery codes, hashed (bcrypt) and single-use;
+ *   - build the otpauth:// URI + QR data-URL for enrollment.
+ *
+ * The encryption key is derived (scrypt) from MFA_ENCRYPTION_KEY when set,
+ * otherwise from JWT_SECRET. Rotating either invalidates stored secrets —
+ * the same blast radius as rotating JWT_SECRET already has for sessions, and
+ * `reset-admin-mfa.js` is the recovery path.
+ */
+
+const crypto = require('crypto');
+const bcrypt = require('bcrypt');
+const { authenticator } = require('otplib');
+const QRCode = require('qrcode');
+
+// Standard TOTP params; window:1 tolerates ±1 step (30s) of clock drift.
+authenticator.options = { window: 1 };
+
+const ISSUER = 'PicPeak';
+const RECOVERY_CODE_COUNT = 10;
+const RECOVERY_CODE_BYTES = 10; // ~80 bits of entropy per code
+const RECOVERY_BCRYPT_ROUNDS = 10;
+
+const ENC_ALGO = 'aes-256-gcm';
+const ENC_SALT = 'picpeak-mfa-secret-v1'; // fixed: derivation must be stable
+
+function getEncryptionKey() {
+  const material = process.env.MFA_ENCRYPTION_KEY || process.env.JWT_SECRET;
+  if (!material) {
+    throw new Error('mfaService: MFA_ENCRYPTION_KEY or JWT_SECRET must be set');
+  }
+  return crypto.scryptSync(material, ENC_SALT, 32);
+}
+
+/** Generate a fresh base32 TOTP secret. */
+function generateSecret() {
+  return authenticator.generateSecret();
+}
+
+/** AES-256-GCM encrypt a secret → "iv.tag.ciphertext" (all base64url). */
+function encryptSecret(plainSecret) {
+  const key = getEncryptionKey();
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ENC_ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(plainSecret, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [iv, tag, ct].map((b) => b.toString('base64url')).join('.');
+}
+
+/** Reverse of encryptSecret. Throws on tamper/wrong key. */
+function decryptSecret(stored) {
+  const key = getEncryptionKey();
+  const [ivB64, tagB64, ctB64] = String(stored).split('.');
+  if (!ivB64 || !tagB64 || !ctB64) {
+    throw new Error('mfaService: malformed encrypted secret');
+  }
+  const decipher = crypto.createDecipheriv(ENC_ALGO, key, Buffer.from(ivB64, 'base64url'));
+  decipher.setAuthTag(Buffer.from(tagB64, 'base64url'));
+  const pt = Buffer.concat([decipher.update(Buffer.from(ctB64, 'base64url')), decipher.final()]);
+  return pt.toString('utf8');
+}
+
+/** Verify a 6-digit TOTP code against the (plaintext) secret. */
+function verifyTotp(code, plainSecret) {
+  if (!code || !plainSecret) return false;
+  try {
+    return authenticator.verify({ token: String(code).replace(/\s+/g, ''), secret: plainSecret });
+  } catch {
+    return false;
+  }
+}
+
+/** Verify a code against a STORED (encrypted) secret. */
+function verifyTotpEncrypted(code, storedSecret) {
+  try {
+    return verifyTotp(code, decryptSecret(storedSecret));
+  } catch {
+    return false;
+  }
+}
+
+/** otpauth:// URI for an authenticator app. */
+function buildOtpauthUri(accountName, plainSecret) {
+  return authenticator.keyuri(accountName, ISSUER, plainSecret);
+}
+
+/** QR code (PNG data URL) for the otpauth URI. */
+async function buildQrDataUrl(otpauthUri) {
+  return QRCode.toDataURL(otpauthUri, { errorCorrectionLevel: 'M', margin: 1, width: 240 });
+}
+
+/** Format a raw code as human-friendly groups, e.g. "abcd-efgh-jk". */
+function formatRecoveryCode(raw) {
+  return raw.match(/.{1,4}/g).join('-');
+}
+
+/**
+ * Generate RECOVERY_CODE_COUNT one-time codes. Returns the plaintext codes
+ * (shown to the admin ONCE) and their bcrypt hashes (persisted).
+ */
+async function generateRecoveryCodes() {
+  const plain = [];
+  const hashed = [];
+  for (let i = 0; i < RECOVERY_CODE_COUNT; i++) {
+    // base32-ish, lowercase, no ambiguous chars
+    const raw = crypto.randomBytes(RECOVERY_CODE_BYTES)
+      .toString('base64')
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .toLowerCase()
+      .slice(0, 10);
+    const code = formatRecoveryCode(raw);
+    plain.push(code);
+    hashed.push(await bcrypt.hash(code, RECOVERY_BCRYPT_ROUNDS));
+  }
+  return { plain, hashed };
+}
+
+function normalizeRecoveryInput(code) {
+  return String(code || '').trim().toLowerCase();
+}
+
+/**
+ * Check a submitted recovery code against the stored hash array. On match,
+ * returns the remaining hashes (matched one removed — single use). On miss,
+ * matched:false and the array unchanged.
+ *
+ * @param {string[]} storedHashes
+ * @returns {Promise<{matched: boolean, remainingHashes: string[]}>}
+ */
+async function consumeRecoveryCode(code, storedHashes) {
+  const input = normalizeRecoveryInput(code);
+  const hashes = Array.isArray(storedHashes) ? storedHashes : [];
+  if (!input) return { matched: false, remainingHashes: hashes };
+  for (let i = 0; i < hashes.length; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await bcrypt.compare(input, hashes[i])) {
+      const remaining = hashes.slice(0, i).concat(hashes.slice(i + 1));
+      return { matched: true, remainingHashes: remaining };
+    }
+  }
+  return { matched: false, remainingHashes: hashes };
+}
+
+/** True when an admin row has MFA enabled (coerces SQLite/PG boolean shapes). */
+function isEnrolled(admin) {
+  const v = admin && admin.two_factor_enabled;
+  return v === true || v === 1 || v === '1';
+}
+
+/** Parse the DB column (JSON text) into an array of hashes. */
+function parseRecoveryCodes(raw) {
+  if (!raw) return [];
+  try {
+    const arr = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  generateSecret,
+  encryptSecret,
+  decryptSecret,
+  verifyTotp,
+  verifyTotpEncrypted,
+  buildOtpauthUri,
+  buildQrDataUrl,
+  generateRecoveryCodes,
+  consumeRecoveryCode,
+  parseRecoveryCodes,
+  isEnrolled,
+  formatRecoveryCode,
+  ISSUER,
+  RECOVERY_CODE_COUNT,
+};