create-efc-app 0.10.0 → 0.10.2

package/dist/index.js

@@ -10,6 +10,251 @@ import path3 from "path";
 import fs from "fs-extra";
 import path from "path";
 import crypto from "crypto";
+
+// src/two-factor.ts
+function twoFactorLibrary(ts, table, collection) {
+  const T = (type) => ts ? type : "";
+  const where = table ? "{ where, data }" : "where, data";
+  const result = table ? "result.count" : collection ? "result.modifiedCount" : "result";
+  const less = table ? "lt" : "$lt";
+  return `import crypto from 'node:crypto';
+import { HttpError } from 'express-file-cluster';
+import { enqueue } from 'express-file-cluster/tasks';
+
+${T(`interface SecurityAccount {
+  id: string;
+  twoFactorEnabled?: boolean;
+  twoFactorSecret?: string;
+  twoFactorLastStep?: number;
+  email: string; twoFactorMethod?: string;
+  twoFactorEmailHash?: string; twoFactorEmailExpiry?: Date; twoFactorEmailPurpose?: string;
+}
+type SecurityData = {
+  twoFactorEnabled?: boolean; twoFactorSecret?: string; twoFactorLastStep?: number;
+  twoFactorMethod?: string; twoFactorPendingMethod?: string;
+  twoFactorEmailHash?: string; twoFactorEmailExpiry?: Date; twoFactorEmailPurpose?: string;
+  twoFactorPendingSecret?: string; twoFactorPendingExpiry?: Date;
+  refreshToken?: string; refreshTokenExpiry?: Date;
+  password?: string; resetToken?: string; resetTokenExpiry?: Date;
+};
+type SecurityWhere = {
+  id: string; password?: string; resetToken?: string; resetTokenExpiry?: { ${table ? "gt" : "$gt"}: Date }; refreshToken?: string; twoFactorEnabled?: ${table ? "boolean" : "boolean | { $ne: true }"}; twoFactorSecret?: string;
+  twoFactorPendingSecret?: string; twoFactorEmailHash?: string; twoFactorPendingMethod?: string; twoFactorLastStep?: { ${less}: number };
+};
+interface SecurityModel {
+  updateMany(${table ? "args: { where: SecurityWhere; data: SecurityData }" : "where: SecurityWhere, data: SecurityData"}): Promise<${table ? "{ count: number }" : collection ? "{ modifiedCount: number }" : "number"}>;
+}
+`)}
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+export function newSecret()${T(": string")} {
+  const bytes = crypto.randomBytes(20);
+  let bits = 0, value = 0, result = '';
+  for (const byte of bytes) {
+    value = (value << 8) | byte; bits += 8;
+    while (bits >= 5) { bits -= 5; result += ALPHABET[(value >>> bits) & 31]; }
+  }
+  return result;
+}
+function secretBytes(secret${T(": string")}) {
+  if (!/^[A-Z2-7]+$/.test(secret)) throw new Error('Invalid TOTP secret');
+  let bits = 0, value = 0;
+  const bytes${T(": number[]")} = [];
+  for (const char of secret) {
+    value = (value << 5) | ALPHABET.indexOf(char); bits += 5;
+    if (bits >= 8) { bits -= 8; bytes.push((value >>> bits) & 255); }
+  }
+  return Buffer.from(bytes);
+}
+// RFC 6238: SHA-1, six digits, 30-second steps, one step of clock drift.
+export function totp(secret${T(": string")}, step${T(": number")})${T(": string")} {
+  const counter = Buffer.alloc(8);
+  counter.writeBigUInt64BE(BigInt(step));
+  const digest = crypto.createHmac('sha1', secretBytes(secret)).update(counter).digest();
+  const offset = digest[digest.length - 1]${T("!")} & 15;
+  return String((digest.readUInt32BE(offset) & 0x7fffffff) % 1000000).padStart(6, '0');
+}
+export function codeStep(secret${T(": string")}, code${T(": unknown")}, last = -1, now = Date.now())${T(": number | undefined")} {
+  if (typeof code !== 'string' || !/^\\d{6}$/.test(code)) return undefined;
+  const step = Math.floor(now / 30000);
+  for (const candidate of [step, step - 1, step + 1]) {
+    if (candidate > last && candidate >= 0 && crypto.timingSafeEqual(Buffer.from(code), Buffer.from(totp(secret, candidate)))) return candidate;
+  }
+  return undefined;
+}
+function encryptionKey() {
+  const key = process.env.TWO_FACTOR_KEY;
+  if (!key || !/^[a-fA-F0-9]{64}$/.test(key)) throw new HttpError(503, 'TWO_FACTOR_KEY must be 32 random bytes encoded as 64 hex characters');
+  return Buffer.from(key, 'hex');
+}
+export function sealSecret(secret${T(": string")}, identity${T(": string")})${T(": string")} {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', encryptionKey(), iv);
+  cipher.setAAD(Buffer.from(identity));
+  const encrypted = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), encrypted]).toString('base64url');
+}
+export function openSecret(encrypted${T(": string")}, identity${T(": string")})${T(": string")} {
+  const key = encryptionKey();
+  try {
+    const data = Buffer.from(encrypted, 'base64url');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, data.subarray(0, 12));
+    decipher.setAAD(Buffer.from(identity));
+    decipher.setAuthTag(data.subarray(12, 28));
+    return Buffer.concat([decipher.update(data.subarray(28)), decipher.final()]).toString('utf8');
+  } catch { throw new HttpError(503, 'Two-factor secret could not be decrypted'); }
+}
+export async function updateSecurity(model${T(": SecurityModel")}, where${T(": SecurityWhere")}, data${T(": SecurityData")})${T(": Promise<boolean>")} {
+${table ? "" : `  // Older MongoDB records may predate the defaulted enabled flag. Missing means off.
+  if (where.twoFactorEnabled === false) where = { ...where, twoFactorEnabled: { $ne: true } };
+`}  const result = await model.updateMany(${where});
+  return ${result} === 1;
+}
+export function allowedMethods()${T(": string[]")} {
+  const value = process.env.TWO_FACTOR_METHOD ?? 'totp';
+  if (!['totp', 'email', 'both'].includes(value)) throw new HttpError(503, 'Invalid TWO_FACTOR_METHOD');
+  return value === 'both' ? ['totp', 'email'] : [value];
+}
+function emailDigest(identity${T(": string")}, purpose${T(": string")}, code${T(": string")}) {
+  return crypto.createHmac('sha256', encryptionKey()).update(identity + ':' + purpose + ':' + code).digest('hex');
+}
+export async function sendEmailCode(model${T(": SecurityModel")}, account${T(": SecurityAccount")}, kind${T(": string")}, purpose${T(": string")}) {
+  if (!process.env.SMTP_HOST) throw new HttpError(503, 'Configure the email-client SMTP settings before using email OTP');
+  const code = String(crypto.randomInt(0, 1000000)).padStart(6, '0');
+  const twoFactorEmailHash = emailDigest(kind + ':' + account.id + ':' + account.email, purpose, code);
+  const updated = await updateSecurity(model, { id: account.id, twoFactorEnabled: !!account.twoFactorEnabled }, {
+    twoFactorEmailHash, twoFactorEmailExpiry: new Date(Date.now() + 300000), twoFactorEmailPurpose: purpose,
+  });
+  if (!updated) throw new HttpError(409, 'Account security changed; try again');
+  try {
+    await enqueue('SendEmail', { to: account.email, subject: 'Your EFC verification code', body: 'Your verification code is <b>' + code + '</b>. It expires in 5 minutes.' });
+  } catch (error) {
+    await updateSecurity(model, { id: account.id, twoFactorEmailHash }, { twoFactorEmailHash: '' });
+    throw error;
+  }
+}
+export async function consumeEmailCode(model${T(": SecurityModel")}, account${T(": SecurityAccount")}, kind${T(": string")}, purpose${T(": string")}, code${T(": unknown")})${T(": Promise<boolean>")} {
+  if (typeof code !== 'string' || !/^\\d{6}$/.test(code) || !account.twoFactorEmailHash || account.twoFactorEmailPurpose !== purpose || !account.twoFactorEmailExpiry || new Date(account.twoFactorEmailExpiry).getTime() <= Date.now()) return false;
+  const digest = emailDigest(kind + ':' + account.id + ':' + account.email, purpose, code);
+  const stored = Buffer.from(account.twoFactorEmailHash, 'hex');
+  const supplied = Buffer.from(digest, 'hex');
+  if (stored.length !== supplied.length || !crypto.timingSafeEqual(stored, supplied)) return false;
+  return updateSecurity(model, { id: account.id, twoFactorEmailHash: account.twoFactorEmailHash, twoFactorEnabled: !!account.twoFactorEnabled }, { twoFactorEmailHash: '', twoFactorEmailExpiry: new Date(0) });
+}
+export async function acceptTwoFactor(model${T(": SecurityModel")}, account${T(": SecurityAccount")}, kind${T(": string")}, code${T(": unknown")}, purpose = 'login')${T(": Promise<boolean>")} {
+  if (!account.twoFactorEnabled) return true;
+  const method = account.twoFactorMethod ?? 'totp';
+  if (!allowedMethods().includes(method)) return false;
+  if (method === 'email') {
+    if (code === undefined) { await sendEmailCode(model, account, kind, purpose); return false; }
+    return consumeEmailCode(model, account, kind, purpose, code);
+  }
+  if (!account.twoFactorSecret) return false;
+  const step = codeStep(openSecret(account.twoFactorSecret, kind + ':' + account.id), code, account.twoFactorLastStep ?? -1);
+  if (step === undefined) return false;
+  // Compare-and-set in the database: only one worker can accept a given code.
+  return updateSecurity(model, { id: account.id, twoFactorEnabled: true, twoFactorSecret: account.twoFactorSecret, twoFactorLastStep: { ${less}: step } }, { twoFactorLastStep: step });
+}
+`;
+}
+function twoFactorRoutes(ts, table, hasAdmin) {
+  const T = (type) => ts ? type : "";
+  const find = (model) => table ? `${model}.findUnique({ where: { id } })` : `${model}.findById(id)`;
+  const imports = `import { requireAuth, getCurrentUser, verifyPassword, revokeAllSessions } from 'express-file-cluster/auth';
+import { HttpError, rateLimit } from 'express-file-cluster';
+${T("import type { Request, Response } from 'express';\n")}import { User } from '../../../model/User.js';
+${hasAdmin ? "import { Admin } from '../../../model/Admin.js';\n" : ""}import { newSecret, sealSecret, openSecret, codeStep, updateSecurity, acceptTwoFactor, allowedMethods, sendEmailCode, consumeEmailCode } from '../../../lib/two-factor.js';
+
+export const middlewares = [requireAuth, rateLimit({ window: '15m', max: 10, name: 'two-factor-management', key: () => String(getCurrentUser()?.id ?? ''), onCacheError: 'reject' })];
+
+async function currentAccount() {
+  const principal = getCurrentUser();
+  if (!principal || typeof principal.id !== 'string') throw new HttpError(401, 'Unauthorized');
+  const id = principal.id;
+  const kind = ${hasAdmin ? "principal.role === 'admin' ? 'admin' : 'user'" : "'user'"};
+  const model = ${hasAdmin ? "kind === 'admin' ? Admin : User" : "User"};
+  const account = ${hasAdmin ? `kind === 'admin' ? await ${find("Admin")} : await ${find("User")}` : `await ${find("User")}`};
+  if (!account || !account.isActive) throw new HttpError(403, 'Account unavailable');
+  return { account, kind, model };
+}
+`;
+  const revoke = `  await revokeAllSessions(account.id);
+  res.clearCookie('efc_refresh_token');
+`;
+  const setup = `${imports}
+export const GET = async (_req${T(": Request")}, res${T(": Response")}) => {
+  const { account } = await currentAccount();
+  res.set('Cache-Control', 'no-store');
+  res.json({ enabled: !!account.twoFactorEnabled, method: account.twoFactorMethod || null, methods: allowedMethods() });
+};
+
+export const POST = async (req${T(": Request")}, res${T(": Response")}) => {
+  res.set('Cache-Control', 'no-store');
+  const { password, code, method = 'totp' } = req.body ?? {};
+  if (typeof password !== 'string' || !password || (code !== undefined && (typeof code !== 'string' || !/^\\d{6}$/.test(code)))) return res.status(400).json({ error: 'password and a six-digit code (when confirming) are required' });
+  const { account, kind, model } = await currentAccount();
+  if (!(await verifyPassword(password, account.password))) return res.status(401).json({ error: 'Invalid credentials' });
+  if (account.twoFactorEnabled) return res.status(409).json({ error: 'Two-factor authentication is already enabled' });
+  const identity = kind + ':' + account.id;
+  if (typeof method !== 'string' || !allowedMethods().includes(method)) return res.status(400).json({ error: 'Choose an allowed two-factor method' });
+  if (code === undefined && method === 'email') {
+    const updated = await updateSecurity(model, { id: account.id, twoFactorEnabled: false }, { twoFactorPendingMethod: 'email', twoFactorPendingSecret: '', twoFactorPendingExpiry: new Date(Date.now() + 300000) });
+    if (!updated) return res.status(409).json({ error: 'Account changed; try again' });
+    await sendEmailCode(model, account, kind, 'enroll');
+    return res.status(202).json({ method: 'email', codeSent: true, expiresIn: 300 });
+  }
+  if (code === undefined) {
+    const secret = newSecret();
+    const encrypted = sealSecret(secret, identity);
+    const updated = await updateSecurity(model, { id: account.id, twoFactorEnabled: false }, { twoFactorPendingMethod: 'totp', twoFactorPendingSecret: encrypted, twoFactorPendingExpiry: new Date(Date.now() + 600000) });
+    if (!updated) return res.status(409).json({ error: 'Account changed; try again' });
+    const issuer = 'EFC';
+    const otpauthUrl = 'otpauth://totp/' + encodeURIComponent(issuer + ':' + account.email) + '?secret=' + secret + '&issuer=' + issuer + '&algorithm=SHA1&digits=6&period=30';
+    return res.json({ method: 'totp', secret, otpauthUrl, expiresIn: 600 });
+  }
+  if (account.twoFactorPendingMethod !== method || !account.twoFactorPendingExpiry || new Date(account.twoFactorPendingExpiry).getTime() <= Date.now()) return res.status(400).json({ error: 'Enrollment expired; start again' });
+  let step = -1;
+  if (method === 'email') {
+    if (!(await consumeEmailCode(model, account, kind, 'enroll', code))) return res.status(401).json({ error: 'Invalid or expired email code' });
+  } else {
+    if (!account.twoFactorPendingSecret) return res.status(400).json({ error: 'Start enrollment first' });
+    const matched = codeStep(openSecret(account.twoFactorPendingSecret, identity), code);
+    if (matched === undefined) return res.status(401).json({ error: 'Invalid authenticator code' });
+    step = matched;
+  }
+  const enabled = await updateSecurity(model, { id: account.id, twoFactorEnabled: false, twoFactorPendingMethod: method, twoFactorPendingSecret: account.twoFactorPendingSecret ?? '' }, {
+    twoFactorEnabled: true, twoFactorMethod: method, twoFactorSecret: method === 'totp' ? (account.twoFactorPendingSecret ?? '') : '', twoFactorLastStep: step,
+    twoFactorPendingMethod: '', twoFactorPendingSecret: '', twoFactorPendingExpiry: new Date(0), refreshToken: '', refreshTokenExpiry: new Date(0),
+  });
+  if (!enabled) return res.status(409).json({ error: 'Enrollment changed; start again' });
+${revoke}  res.json({ message: '2FA enabled; log in again with your verification code' });
+};
+`;
+  const verify = `export { middlewares, POST } from '../login.js';
+`;
+  const disable = `${imports}
+export const POST = async (req${T(": Request")}, res${T(": Response")}) => {
+  const { password, code } = req.body ?? {};
+  if (typeof password !== 'string' || !password || (code !== undefined && (typeof code !== 'string' || !/^\\d{6}$/.test(code)))) return res.status(400).json({ error: 'password and a six-digit code are required' });
+  const { account, kind, model } = await currentAccount();
+  if (!(await verifyPassword(password, account.password))) return res.status(401).json({ error: 'Invalid credentials' });
+  if (!account.twoFactorEnabled) return res.status(409).json({ error: 'Two-factor authentication is not enabled' });
+  if (account.twoFactorMethod === 'email' && code === undefined) {
+    await sendEmailCode(model, account, kind, 'disable');
+    return res.status(202).json({ codeSent: true, expiresIn: 300 });
+  }
+  if (!(await acceptTwoFactor(model, account, kind, code, 'disable'))) return res.status(401).json({ error: 'Invalid or already used authenticator code' });
+  const disabled = await updateSecurity(model, { id: account.id, twoFactorEnabled: true, twoFactorSecret: account.twoFactorSecret ?? '' }, {
+    twoFactorEnabled: false, twoFactorMethod: '', twoFactorSecret: '', twoFactorLastStep: -1, twoFactorPendingSecret: '', twoFactorPendingMethod: '', twoFactorEmailHash: '', twoFactorEmailExpiry: new Date(0),
+    twoFactorPendingExpiry: new Date(0), refreshToken: '', refreshTokenExpiry: new Date(0),
+  });
+  if (!disabled) return res.status(409).json({ error: 'Account changed; try again' });
+${revoke}  res.json({ message: '2FA disabled; log in again' });
+};
+`;
+  return { "2fa/setup": setup, "2fa/verify": verify, "2fa/disable": disable };
+}
+
+// src/scaffold.ts
 var NO_ADMIN_FEATURES = {
   userManagement: false,
   adminManagement: false,
@@ -157,7 +402,7 @@ async function scaffold(opts) {
 }
 async function writePackageJson(dest, opts) {
   const deps = {
-    "express-file-cluster": "^0.10.0"
+    "express-file-cluster": "^0.10.2"
   };
   if (opts.database === "mongodb") deps["mongoose"] = "^9.7.2";
   if (opts.database === "postgresql") {
@@ -321,8 +566,8 @@ ${usesTables(opts) ? `- \`src/model/*.${ext}\` \u2014 \`defineTable\` models (Po
   them all${opts.language === "typescript" ? " and declares `Tables` (typed `include`)" : ""} \u2014 add new models there.` : usesCollections(opts) ? `- \`src/model/*.${ext}\` \u2014 \`defineCollection\` models (MongoDB-native, mongoose-style queries:
   \`find(filter, { projection, sort })\`, \`findByIdAndUpdate\`, typed \`pipeline()\`, \`lookup()\`).` : `- \`src/model/*.${ext}\` \u2014 \`defineModel\` models.`}
 - \`src/index.${ext}\` is the entry point; it imports \`efc.config.${ext}\` and passes it to \`ignite()\`.
-- Only three import paths exist: \`express-file-cluster\`, \`express-file-cluster/auth\`,
-  \`express-file-cluster/tasks\`.
+- Four import paths exist: \`express-file-cluster\`, \`express-file-cluster/auth\`,
+  \`express-file-cluster/tasks\`, and \`express-file-cluster/testing\` (\`createTestApp\` for route tests).
 ${opts.registry ? `- Ready-made features (auth, user/admin portals, billing, mailer\u2026) come from the registry:
   \`npx efc list\`, then \`npx efc add <item> --yes\` \u2014 check it before hand-writing auth or CRUD
   (\`${D}/cli/add.md\`). \`efc.json\` tracks what was added; commit it.
@@ -399,12 +644,13 @@ ${k}=${ex}`).join("");
   const dotenv = `PORT=3000
 NODE_ENV=development
 DATABASE_URL=${dbUrl}
-JWT_SECRET=${secret}${redis}
+JWT_SECRET=${secret}${opts.userFeatures.accountSecurity ? "\nTWO_FACTOR_METHOD=totp" : ""}${principals(opts).user || principals(opts).admin ? `
+TWO_FACTOR_KEY=${crypto.randomBytes(32).toString("hex")}` : ""}${redis}
 CORS_ORIGINS=http://localhost:3000${smtpVars}${oauthEnv}`;
   const example = `PORT=3000
 NODE_ENV=development
 DATABASE_URL=${dbExampleUrl}
-JWT_SECRET=<generate with: openssl rand -hex 64>${redis}
+JWT_SECRET=<generate with: openssl rand -hex 64>${opts.userFeatures.accountSecurity ? "\nTWO_FACTOR_METHOD=totp" : ""}${principals(opts).user || principals(opts).admin ? "\nTWO_FACTOR_KEY=<generate with: openssl rand -hex 32>" : ""}${redis}
 CORS_ORIGINS=http://localhost:3000,https://yourapp.com
 # Behind a proxy / load balancer: how many hops to trust, so rate limits see client IPs
 # TRUST_PROXY=1${smtpExample}${oauthExample}`;
@@ -533,6 +779,16 @@ export const User = ${modelApi(opts).name}('User', {
   resetTokenExpiry:   { type: 'date' },
   refreshToken:       { type: 'string' },
   refreshTokenExpiry: { type: 'date' },
+  twoFactorEnabled:   { type: 'boolean', default: false },
+  twoFactorSecret:    { type: 'string', default: '' },
+  twoFactorLastStep:  { type: 'number', default: -1 },
+  twoFactorPendingSecret: { type: 'string', default: '' },
+  twoFactorPendingExpiry: { type: 'date' },
+  twoFactorMethod: { type: 'string', default: '' },
+  twoFactorPendingMethod: { type: 'string', default: '' },
+  twoFactorEmailHash: { type: 'string', default: '' },
+  twoFactorEmailExpiry: { type: 'date' },
+  twoFactorEmailPurpose: { type: 'string', default: '' },
 }${relationsOption(opts, [
     { name: "sessions", kind: "hasMany", target: "Session", foreignKey: "user" },
     { name: "notifications", kind: "hasMany", target: "Notification", foreignKey: "user" },
@@ -560,6 +816,16 @@ export const Admin = ${modelApi(opts).name}('Admin', {
   resetTokenExpiry:   { type: 'date' },
   refreshToken:       { type: 'string' },
   refreshTokenExpiry: { type: 'date' },
+  twoFactorEnabled:   { type: 'boolean', default: false },
+  twoFactorSecret:    { type: 'string', default: '' },
+  twoFactorLastStep:  { type: 'number', default: -1 },
+  twoFactorPendingSecret: { type: 'string', default: '' },
+  twoFactorPendingExpiry: { type: 'date' },
+  twoFactorMethod: { type: 'string', default: '' },
+  twoFactorPendingMethod: { type: 'string', default: '' },
+  twoFactorEmailHash: { type: 'string', default: '' },
+  twoFactorEmailExpiry: { type: 'date' },
+  twoFactorEmailPurpose: { type: 'string', default: '' },
 }${relationsOption(opts, [
     { name: "assignedTickets", kind: "hasMany", target: "SupportTicket", foreignKey: "assignedTo" },
     { name: "auditLogs", kind: "hasMany", target: "AuditLog", foreignKey: "admin" },
@@ -593,7 +859,13 @@ export const meta: RouteMeta = {
 ` : "";
   const { user: hasUser, admin: hasAdmin } = principals(opts);
   const hasModels = hasUser || hasAdmin;
+  if (hasModels)
+    await fs.outputFile(
+      path.join(dest, "src", "lib", `two-factor.${ext}`),
+      twoFactorLibrary(ts, usesTables(opts), usesCollections(opts))
+    );
   const loginDbImports = hasModels ? `import crypto from 'node:crypto';
+import { acceptTwoFactor, updateSecurity } from '../../lib/two-factor.js';
 ${hasUser ? `import { User } from '../../model/User.js';
 ` : ""}${hasAdmin ? `import { Admin } from '../../model/Admin.js';
 ` : ""}` : "";
@@ -602,8 +874,9 @@ ${hasUser ? `import { User } from '../../model/User.js';
     const match = await verifyPassword(password, admin.password);
     if (!match) return res.status(401).json({ error: 'Invalid credentials' });
     if (!admin.isActive) return res.status(403).json({ error: 'Account suspended' });
-    const token = await issueToken(res, { id: admin.id, role: admin.role, email: admin.email });
-    const refreshToken = await issueRefreshToken(res, Admin, admin.id);
+  if (!(await acceptTwoFactor(Admin, admin, 'admin', req.body?.code))) return res.status(401).json({ error: 'Verification code required or invalid', twoFactorRequired: true, method: admin.twoFactorMethod || 'totp' });
+    const refreshToken = await issueRefreshToken(res, Admin, admin);
+    const token = await issueToken(res, { id: admin.id, role: admin.role, email: admin.email, efc_auth_at: authenticatedAt });
     return res.json({ message: 'Logged in as admin', ...(token ? { token, refreshToken } : {}) });
   }
 
@@ -612,29 +885,32 @@ ${hasUser ? `import { User } from '../../model/User.js';
   const match = await verifyPassword(password, user.password);
   if (!match) return res.status(401).json({ error: 'Invalid credentials' });
   if (!user.isActive) return res.status(403).json({ error: 'Account suspended' });
-  const token = await issueToken(res, { id: user.id, role: user.role, email: user.email });
-  const refreshToken = await issueRefreshToken(res, User, user.id);
+  if (!(await acceptTwoFactor(User, user, 'user', req.body?.code))) return res.status(401).json({ error: 'Verification code required or invalid', twoFactorRequired: true, method: user.twoFactorMethod || 'totp' });
+  const refreshToken = await issueRefreshToken(res, User, user);
+  const token = await issueToken(res, { id: user.id, role: user.role, email: user.email, efc_auth_at: authenticatedAt });
   // bearer: the client stores both tokens itself; http-only: they travel as cookies.
   res.json({ message: 'Logged in', ...(token ? { token, refreshToken } : {}) });` : hasAdmin ? `  const admin = await ${db.findOne("Admin", `{ email }`)};
   if (!admin) return res.status(401).json({ error: 'Invalid credentials' });
   const match = await verifyPassword(password, admin.password);
   if (!match) return res.status(401).json({ error: 'Invalid credentials' });
   if (!admin.isActive) return res.status(403).json({ error: 'Account suspended' });
-  const token = await issueToken(res, { id: admin.id, role: admin.role, email: admin.email });
-  const refreshToken = await issueRefreshToken(res, Admin, admin.id);
+  if (!(await acceptTwoFactor(Admin, admin, 'admin', req.body?.code))) return res.status(401).json({ error: 'Verification code required or invalid', twoFactorRequired: true, method: admin.twoFactorMethod || 'totp' });
+  const refreshToken = await issueRefreshToken(res, Admin, admin);
+  const token = await issueToken(res, { id: admin.id, role: admin.role, email: admin.email, efc_auth_at: authenticatedAt });
   // bearer: the client stores both tokens itself; http-only: they travel as cookies.
   res.json({ message: 'Logged in as admin', ...(token ? { token, refreshToken } : {}) });` : `  const user = await ${db.findOne("User", `{ email }`)};
   if (!user) return res.status(401).json({ error: 'Invalid credentials' });
   const match = await verifyPassword(password, user.password);
   if (!match) return res.status(401).json({ error: 'Invalid credentials' });
   if (!user.isActive) return res.status(403).json({ error: 'Account suspended' });
-  const token = await issueToken(res, { id: user.id, role: user.role, email: user.email });
-  const refreshToken = await issueRefreshToken(res, User, user.id);
+  if (!(await acceptTwoFactor(User, user, 'user', req.body?.code))) return res.status(401).json({ error: 'Verification code required or invalid', twoFactorRequired: true, method: user.twoFactorMethod || 'totp' });
+  const refreshToken = await issueRefreshToken(res, User, user);
+  const token = await issueToken(res, { id: user.id, role: user.role, email: user.email, efc_auth_at: authenticatedAt });
   // bearer: the client stores both tokens itself; http-only: they travel as cookies.
   res.json({ message: 'Logged in', ...(token ? { token, refreshToken } : {}) });`;
   const loginContent = hasModels ? ts ? `import { issueToken, verifyPassword } from 'express-file-cluster/auth';
 import type { Request, Response } from 'express';
-import { rateLimit } from 'express-file-cluster';
+import { HttpError, rateLimit } from 'express-file-cluster';
 ${loginDbImports}${loginMeta}// 10 attempts per 15 minutes per address and account. Keyed on the email too, so behind a
 // proxy without TRUST_PROXY (every client then has the proxy's IP) it still limits one
 // account at a time, never everyone.
@@ -642,7 +918,9 @@ export const middlewares = [
   rateLimit({
     window: '15m',
     max: 10,
-    key: (req) => \`\${req.ip}:\${String(req.body?.email ?? '').toLowerCase()}\`,
+    name: 'password-login',
+    onCacheError: 'reject',
+    key: (req) => String(req.body?.email ?? '').toLowerCase(),
   }),
 ];
 
@@ -650,11 +928,12 @@ const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
 
 async function issueRefreshToken(
   res: Response,
-  model: ${usesTables(opts) ? "{ update: (args: { where: { id: string }; data: Record<string, unknown> }) => Promise<unknown> }" : usesCollections(opts) ? "{ findByIdAndUpdate: (id: string, data: Record<string, unknown>, options: { returnDocument: 'after' }) => Promise<unknown> }" : "{ update: (id: string, data: Record<string, unknown>) => Promise<unknown> }"},
-  id: string,
+  model: Parameters<typeof updateSecurity>[0],
+  account: { id: string; password: string; twoFactorEnabled?: boolean; twoFactorSecret?: string },
 ): Promise<string> {
   const refreshToken = crypto.randomBytes(40).toString('hex');
-  await ${db.update("model", "id", "{ refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) }")};
+  const updated = await updateSecurity(model, { id: account.id, password: account.password, twoFactorEnabled: !!account.twoFactorEnabled, ...(account.twoFactorEnabled ? { twoFactorSecret: account.twoFactorSecret ?? '' } : {}) }, { refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) });
+  if (!updated) throw new HttpError(409, 'Account security changed; log in again');
   res.cookie('efc_refresh_token', refreshToken, {
     httpOnly: true,
     secure: process.env.NODE_ENV === 'production',
@@ -665,7 +944,8 @@ async function issueRefreshToken(
 }
 
 export const POST = async (req: Request, res: Response) => {
-  const { email, password } = req.body;
+  const authenticatedAt = Date.now();
+  const { email, password } = req.body ?? {};
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
   if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
     return res.status(400).json({ error: 'email and password are required' });
@@ -674,7 +954,7 @@ export const POST = async (req: Request, res: Response) => {
 ${loginBody}
 };
 ` : `import { issueToken, verifyPassword } from 'express-file-cluster/auth';
-import { rateLimit } from 'express-file-cluster';
+import { HttpError, rateLimit } from 'express-file-cluster';
 ${loginDbImports}${loginMeta}// 10 attempts per 15 minutes per address and account. Keyed on the email too, so behind a
 // proxy without TRUST_PROXY (every client then has the proxy's IP) it still limits one
 // account at a time, never everyone.
@@ -682,15 +962,18 @@ export const middlewares = [
   rateLimit({
     window: '15m',
     max: 10,
-    key: (req) => \`\${req.ip}:\${String(req.body?.email ?? '').toLowerCase()}\`,
+    name: 'password-login',
+    onCacheError: 'reject',
+    key: (req) => String(req.body?.email ?? '').toLowerCase(),
   }),
 ];
 
 const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
 
-async function issueRefreshToken(res, model, id) {
+async function issueRefreshToken(res, model, account) {
   const refreshToken = crypto.randomBytes(40).toString('hex');
-  await ${db.update("model", "id", "{ refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) }")};
+  const updated = await updateSecurity(model, { id: account.id, password: account.password, twoFactorEnabled: !!account.twoFactorEnabled, ...(account.twoFactorEnabled ? { twoFactorSecret: account.twoFactorSecret ?? '' } : {}) }, { refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) });
+  if (!updated) throw new HttpError(409, 'Account security changed; log in again');
   res.cookie('efc_refresh_token', refreshToken, {
     httpOnly: true,
     secure: process.env.NODE_ENV === 'production',
@@ -701,7 +984,8 @@ async function issueRefreshToken(res, model, id) {
 }
 
 export const POST = async (req, res) => {
-  const { email, password } = req.body;
+  const authenticatedAt = Date.now();
+  const { email, password } = req.body ?? {};
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
   if (typeof email !== 'string' || typeof password !== 'string' || !email || !password) {
     return res.status(400).json({ error: 'email and password are required' });
@@ -740,18 +1024,30 @@ export const meta: RouteMeta = {
 };
 
 ` : "";
-  const logoutContent = ts ? `import { revokeSession } from 'express-file-cluster/auth';
+  const logoutDbImports = hasModels ? `import { updateSecurity } from '../../lib/two-factor.js';
+${hasUser ? "import { User } from '../../model/User.js';\n" : ""}${hasAdmin ? "import { Admin } from '../../model/Admin.js';\n" : ""}` : "";
+  const logoutInvalidate = hasModels ? `  const principal = getCurrentUser();
+  if (!principal || typeof principal.id !== 'string') return res.status(401).json({ error: 'Unauthorized' });
+  const id = principal.id;
+${hasUser ? `  const user = ${hasAdmin ? "principal.role === 'admin' ? null : " : ""}await ${db.findById("User", "id")};
+  if (user?.refreshToken) await updateSecurity(User, { id, refreshToken: user.refreshToken }, { refreshToken: '', refreshTokenExpiry: new Date(0) });` : ""}
+${hasAdmin ? `  const admin = ${hasUser ? "principal.role === 'admin' ? " : ""}await ${db.findById("Admin", "id")}${hasUser ? " : null" : ""};
+  if (admin?.refreshToken) await updateSecurity(Admin, { id, refreshToken: admin.refreshToken }, { refreshToken: '', refreshTokenExpiry: new Date(0) });` : ""}
+` : "";
+  const logoutAuthImports = hasModels ? "requireAuth, getCurrentUser, revokeSession" : "revokeSession";
+  const logoutMiddlewares = hasModels ? "export const middlewares = [requireAuth];\n\n" : "";
+  const logoutContent = ts ? `import { ${logoutAuthImports} } from 'express-file-cluster/auth';
 import type { Request, Response } from 'express';
-${logoutMeta}export const POST = async (req: Request, res: Response) => {
+${logoutDbImports}${logoutMeta}${logoutMiddlewares}export const POST = async (req: Request, res: Response) => {
   // Rejects this token from now on (not just the cookie) \u2014 see \`cache\` in efc.config.
-  await revokeSession(req, res);
+${logoutInvalidate}  await revokeSession(req, res);
   res.clearCookie('efc_refresh_token');
   res.json({ message: 'Logged out successfully' });
 };
-` : `import { revokeSession } from 'express-file-cluster/auth';
-${logoutMeta}export const POST = async (req, res) => {
+` : `import { ${logoutAuthImports} } from 'express-file-cluster/auth';
+${logoutDbImports}${logoutMeta}${logoutMiddlewares}export const POST = async (req, res) => {
   // Rejects this token from now on (not just the cookie) \u2014 see \`cache\` in efc.config.
-  await revokeSession(req, res);
+${logoutInvalidate}  await revokeSession(req, res);
   res.clearCookie('efc_refresh_token');
   res.json({ message: 'Logged out successfully' });
 };
@@ -805,7 +1101,7 @@ ${registerDbImports}${registerMeta}export const POST = async (req: Request, res:
   const verifyToken = crypto.randomBytes(32).toString('hex');
   const user = await ${db.create("User", `{ name, email, password: hashed, verifyToken }`)};
 ${sendVerifyEmail}
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.status(201).json({ message: 'Account created successfully', user: safe });
 };
 ` : `${registerDbImports}${registerMeta}export const POST = async (req, res) => {
@@ -820,7 +1116,7 @@ ${sendVerifyEmail}
   const verifyToken = crypto.randomBytes(32).toString('hex');
   const user = await ${db.create("User", `{ name, email, password: hashed, verifyToken }`)};
 ${sendVerifyEmail}
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.status(201).json({ message: 'Account created successfully', user: safe });
 };
 `;
@@ -972,7 +1268,7 @@ export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const page = Math.max(1, Number(req.query.page) || 1);
   const limit = Math.min(100, Number(req.query.limit) || 20);
   const [all, total] = await Promise.all([${db.find("User", `{}`)}, ${db.count("User", `{}`)}]);
-  const users = all.slice((page - 1) * limit, page * limit).map(({ password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...u }) => u);
+  const users = all.slice((page - 1) * limit, page * limit).map(({ password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...u }) => u);
   res.json({ users, total, page, limit });
 };
 
@@ -986,7 +1282,7 @@ ${roleGuard}  const { name, email, password, role } = req.body;
   if (existing) return res.status(409).json({ error: 'Email already in use' });
   const hashed = await hashPassword(password);
   const user = await ${db.create("User", `{ name, email, password: hashed, role: role ?? 'user' }`)};
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.status(201).json({ message: 'User created', user: safe });
 };
 ` : `import { hashPassword, requireAuth } from 'express-file-cluster/auth';
@@ -995,7 +1291,7 @@ export const GET = async (req, res) => {
 ${roleGuard}  const page = Math.max(1, Number(req.query.page) || 1);
   const limit = Math.min(100, Number(req.query.limit) || 20);
   const [all, total] = await Promise.all([${db.find("User", `{}`)}, ${db.count("User", `{}`)}]);
-  const users = all.slice((page - 1) * limit, page * limit).map(({ password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...u }) => u);
+  const users = all.slice((page - 1) * limit, page * limit).map(({ password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...u }) => u);
   res.json({ users, total, page, limit });
 };
 
@@ -1009,7 +1305,7 @@ ${roleGuard}  const { name, email, password, role } = req.body;
   if (existing) return res.status(409).json({ error: 'Email already in use' });
   const hashed = await hashPassword(password);
   const user = await ${db.create("User", `{ name, email, password: hashed, role: role ?? 'user' }`)};
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.status(201).json({ message: 'User created', user: safe });
 };
 `;
@@ -1065,7 +1361,7 @@ export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   const user = await ${db.findById("User", `id`)};
   if (!user) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.json({ user: safe });
 };
 
@@ -1077,7 +1373,7 @@ ${roleGuard}  const { id } = req.params;
   // The role lives in the user's JWTs: end them, or a demoted/suspended user keeps access
   // until they expire. (/auth/refresh also refuses inactive accounts.)
   if (role !== undefined || isActive === false) await revokeAllSessions(id);
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = updated;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = updated;
   res.json({ message: 'User updated', user: safe });
 };
 
@@ -1095,7 +1391,7 @@ export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   const user = await ${db.findById("User", `id`)};
   if (!user) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.json({ user: safe });
 };
 
@@ -1107,7 +1403,7 @@ ${roleGuard}  const { id } = req.params;
   // The role lives in the user's JWTs: end them, or a demoted/suspended user keeps access
   // until they expire. (/auth/refresh also refuses inactive accounts.)
   if (role !== undefined || isActive === false) await revokeAllSessions(id);
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = updated;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = updated;
   res.json({ message: 'User updated', user: safe });
 };
 
@@ -1168,16 +1464,20 @@ export const GET = async (req: Request, res: Response) => {
   const { id } = (req as any).user;
   const user = await ${db.findById("User", `id`)};
   if (!user) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.json({ user: safe });
 };
 
 export const PUT = async (req: Request, res: Response) => {
   const { id } = (req as any).user;
-  const { name, email } = req.body;
+  const { name, email } = req.body ?? {};
+  if ((name !== undefined && typeof name !== 'string') || (email !== undefined && typeof email !== 'string')) return res.status(400).json({ error: 'name and email must be strings' });
+  const existing = await ${db.findById("User", `id`)};
+  if (!existing) return res.status(404).json({ error: 'User not found' });
+  if (email !== undefined && email !== existing.email && existing.twoFactorEnabled && existing.twoFactorMethod === 'email') return res.status(409).json({ error: 'Disable email 2FA before changing the email address' });
   const updated = await ${db.update("User", `id`, `{ name, email }`)};
   if (!updated) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = updated;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = updated;
   res.json({ message: 'Profile updated', user: safe });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
@@ -1186,16 +1486,20 @@ export const GET = async (req, res) => {
   const { id } = req.user;
   const user = await ${db.findById("User", `id`)};
   if (!user) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = user;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = user;
   res.json({ user: safe });
 };
 
 export const PUT = async (req, res) => {
   const { id } = req.user;
-  const { name, email } = req.body;
+  const { name, email } = req.body ?? {};
+  if ((name !== undefined && typeof name !== 'string') || (email !== undefined && typeof email !== 'string')) return res.status(400).json({ error: 'name and email must be strings' });
+  const existing = await ${db.findById("User", `id`)};
+  if (!existing) return res.status(404).json({ error: 'User not found' });
+  if (email !== undefined && email !== existing.email && existing.twoFactorEnabled && existing.twoFactorMethod === 'email') return res.status(409).json({ error: 'Disable email 2FA before changing the email address' });
   const updated = await ${db.update("User", `id`, `{ name, email }`)};
   if (!updated) return res.status(404).json({ error: 'User not found' });
-  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, ...safe } = updated;
+  const { password: _, verifyToken: _vt, resetToken: _rt, resetTokenExpiry: _re, refreshToken: _ft, refreshTokenExpiry: _fe, twoFactorSecret: _tfs, twoFactorPendingSecret: _tfp, twoFactorPendingExpiry: _tfpe, twoFactorLastStep: _tfl, twoFactorEmailHash: _tfeh, twoFactorEmailExpiry: _tfee, twoFactorEmailPurpose: _tfep, twoFactorPendingMethod: _tfpm, ...safe } = updated;
   res.json({ message: 'Profile updated', user: safe });
 };
 `;
@@ -1483,14 +1787,18 @@ ${hasAdmin ? `import { Admin } from '../../model/Admin.js';
   const admin = user ? null : await ${db.findOne("Admin", `{ refreshToken: token }`)};
   const account = user || admin;` : `  const user = await ${db.findOne("User", `{ refreshToken: token }`)};
   const account = user;`;
-    const refreshPersist = hasAdmin ? `  if (user) await ${db.update("User", `user.id`, `{ refreshToken: newRefreshToken, refreshTokenExpiry }`)};
-  else if (admin) await ${db.update("Admin", `admin.id`, `{ refreshToken: newRefreshToken, refreshTokenExpiry }`)};` : `  await ${db.update("User", `user.id`, `{ refreshToken: newRefreshToken, refreshTokenExpiry }`)};`;
+    const refreshPersist = hasAdmin ? `  const model = user ? User : Admin;
+  const rotated = await updateSecurity(model, { id: account.id, refreshToken: token, twoFactorEnabled: !!account.twoFactorEnabled }, { refreshToken: newRefreshToken, refreshTokenExpiry });
+  if (!rotated) return res.status(401).json({ error: 'Refresh token expired or already used' });` : `  const rotated = await updateSecurity(User, { id: account.id, refreshToken: token, twoFactorEnabled: !!account.twoFactorEnabled }, { refreshToken: newRefreshToken, refreshTokenExpiry });
+  if (!rotated) return res.status(401).json({ error: 'Refresh token expired or already used' });`;
     const refreshContent = ts ? `import { issueToken } from 'express-file-cluster/auth';
 import type { Request, Response } from 'express';
 import crypto from 'node:crypto';
+import { updateSecurity } from '../../lib/two-factor.js';
 ${refreshModelImports}${refreshMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
 
 export const POST = async (req: Request, res: Response) => {
+  const authenticatedAt = Date.now();
   const token = req.cookies?.['efc_refresh_token'] || req.body?.refreshToken;
   if (!token) return res.status(401).json({ error: 'Refresh token required' });
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
@@ -1514,7 +1822,7 @@ ${refreshPersist}
     maxAge: REFRESH_TOKEN_TTL_MS,
   });
 
-  const accessToken = await issueToken(res, { id: account.id, role: account.role, email: account.email });
+  const accessToken = await issueToken(res, { id: account.id, role: account.role, email: account.email, efc_auth_at: authenticatedAt });
   // bearer: the client stores both tokens itself; http-only: they travel as cookies.
   res.json({
     message: 'Token refreshed',
@@ -1523,9 +1831,11 @@ ${refreshPersist}
 };
 ` : `import { issueToken } from 'express-file-cluster/auth';
 import crypto from 'node:crypto';
+import { updateSecurity } from '../../lib/two-factor.js';
 ${refreshModelImports}${refreshMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
 
 export const POST = async (req, res) => {
+  const authenticatedAt = Date.now();
   const token = req.cookies?.efc_refresh_token || req.body?.refreshToken;
   if (!token) return res.status(401).json({ error: 'Refresh token required' });
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
@@ -1549,7 +1859,7 @@ ${refreshPersist}
     maxAge: REFRESH_TOKEN_TTL_MS,
   });
 
-  const accessToken = await issueToken(res, { id: account.id, role: account.role, email: account.email });
+  const accessToken = await issueToken(res, { id: account.id, role: account.role, email: account.email, efc_auth_at: authenticatedAt });
   // bearer: the client stores both tokens itself; http-only: they travel as cookies.
   res.json({
     message: 'Token refreshed',
@@ -1713,12 +2023,14 @@ ${hasAdmin ? `import { Admin } from '../../model/Admin.js';
   const admin = user ? null : await ${db.findOne("Admin", `{ resetToken: token }`)};
   const account = user || admin;` : `  const user = await ${db.findOne("User", `{ resetToken: token }`)};
   const account = user;`;
-    const rpPersist = hasAdmin ? `  if (user) await ${db.update("User", `user.id`, `{ password: hashed, resetToken: '' }`)};
-  else if (admin) await ${db.update("Admin", `admin.id`, `{ password: hashed, resetToken: '' }`)};` : `  await ${db.update("User", `user.id`, `{ password: hashed, resetToken: '' }`)};`;
+    const resetData = `{ password: hashed, resetToken: '', resetTokenExpiry: new Date(0), refreshToken: '', refreshTokenExpiry: new Date(0), twoFactorPendingSecret: '', twoFactorPendingMethod: '', twoFactorPendingExpiry: new Date(0), twoFactorEmailHash: '', twoFactorEmailExpiry: new Date(0) }`;
+    const resetWhere = `{ id: account.id, resetToken: token, resetTokenExpiry: { ${usesTables(opts) ? "gt" : "$gt"}: new Date() } }`;
+    const rpPersist = hasAdmin ? `  const consumed = await updateSecurity(user ? User : Admin, ${resetWhere}, ${resetData});` : `  const consumed = await updateSecurity(User, ${resetWhere}, ${resetData});`;
     const rpContent = ts ? `import type { Request, Response } from 'express';
 import { hashPassword, revokeAllSessions } from 'express-file-cluster/auth';
+import { updateSecurity } from '../../lib/two-factor.js';
 ${rpModelImports}${rpMeta}export const POST = async (req: Request, res: Response) => {
-  const { token, password } = req.body;
+  const { token, password } = req.body ?? {};
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
   if (typeof token !== 'string' || typeof password !== 'string' || !token || !password) {
     return res.status(400).json({ error: 'token and password are required' });
@@ -1732,14 +2044,16 @@ ${rpLookup}
 
   const hashed = await hashPassword(password);
 ${rpPersist}
+  if (!consumed) return res.status(400).json({ error: 'Invalid, expired or already used reset token' });
   // Tokens issued with the old password stop working everywhere.
   await revokeAllSessions(account.id);
 
   res.json({ message: 'Password reset successfully' });
 };
 ` : `import { hashPassword, revokeAllSessions } from 'express-file-cluster/auth';
+import { updateSecurity } from '../../lib/two-factor.js';
 ${rpModelImports}${rpMeta}export const POST = async (req, res) => {
-  const { token, password } = req.body;
+  const { token, password } = req.body ?? {};
   // Strings only: an object such as {"$ne": null} would be read as a filter operator and match any account.
   if (typeof token !== 'string' || typeof password !== 'string' || !token || !password) {
     return res.status(400).json({ error: 'token and password are required' });
@@ -1753,6 +2067,7 @@ ${rpLookup}
 
   const hashed = await hashPassword(password);
 ${rpPersist}
+  if (!consumed) return res.status(400).json({ error: 'Invalid, expired or already used reset token' });
   // Tokens issued with the old password stop working everywhere.
   await revokeAllSessions(account.id);
 
@@ -1769,165 +2084,77 @@ ${rpPersist}
         response: `{ message: 'Password changed successfully' }`
       }
     });
-    const cpContent = ts ? `${RA}import type { Request, Response } from 'express';
-${cpMeta}${mwUser2}
-export const POST = async (req: Request, res: Response) => {
-  const { oldPassword, newPassword } = req.body;
-  if (!oldPassword || !newPassword) return res.status(400).json({ error: 'oldPassword and newPassword are required' });
-  // TODO: verify old password, hash and update new password, then sign out other devices:
-  // await revokeAllSessions(req.user.id)  (import from 'express-file-cluster/auth')
-  res.json({ message: 'Password changed successfully' });
-};
-` : `${RA}${cpMeta}${mwUser2}
-export const POST = async (req, res) => {
-  const { oldPassword, newPassword } = req.body;
-  if (!oldPassword || !newPassword) return res.status(400).json({ error: 'oldPassword and newPassword are required' });
-  // TODO: verify old password, hash and update new password, then sign out other devices:
-  // await revokeAllSessions(req.user.id)  (import from 'express-file-cluster/auth')
+    const cpImports = `import { requireAuth, getCurrentUser, hashPassword, verifyPassword, revokeAllSessions } from 'express-file-cluster/auth';
+import { rateLimit } from 'express-file-cluster';
+import { User } from '../../model/User.js';
+${hasAdmin ? "import { Admin } from '../../model/Admin.js';\n" : ""}`;
+    const cpLookup = hasAdmin ? `  const isAdmin = principal.role === 'admin';
+  const account = isAdmin ? await ${db.findById("Admin", "id")} : await ${db.findById("User", "id")};` : `  const account = await ${db.findById("User", "id")};`;
+    const passwordData = `{ password: hashed, refreshToken: '', refreshTokenExpiry: new Date(0), resetToken: '', resetTokenExpiry: new Date(0) }`;
+    const cpPersist = hasAdmin ? `  const updated = isAdmin ? await ${db.update("Admin", "id", passwordData)} : await ${db.update("User", "id", passwordData)};` : `  const updated = await ${db.update("User", "id", passwordData)};`;
+    const cpContent = `${cpImports}${ts ? "import type { Request, Response } from 'express';\n" : ""}${cpMeta}
+export const middlewares = [
+  ${opts.rbac ? "requireAuth('user', 'admin')" : "requireAuth"},
+  rateLimit({ window: '15m', max: 10, name: 'change-password', key: () => String(getCurrentUser()?.id ?? '') }),
+];
+
+export const POST = async (req${ts ? ": Request" : ""}, res${ts ? ": Response" : ""}) => {
+  const { oldPassword, newPassword } = req.body ?? {};
+  if (typeof oldPassword !== 'string' || typeof newPassword !== 'string' || !oldPassword || !newPassword) {
+    return res.status(400).json({ error: 'oldPassword and newPassword are required' });
+  }
+  const principal = getCurrentUser();
+  if (!principal || typeof principal.id !== 'string' || !principal.id) return res.status(401).json({ error: 'Unauthorized' });
+  const id = principal.id;
+${cpLookup}
+  if (!account || !(await verifyPassword(oldPassword, account.password))) {
+    return res.status(401).json({ error: 'Invalid credentials' });
+  }
+  if (!account.isActive) return res.status(403).json({ error: 'Account suspended' });
+  const hashed = await hashPassword(newPassword);
+${cpPersist}
+  if (!updated) return res.status(404).json({ error: 'Account not found' });
+  await revokeAllSessions(id);
+  res.clearCookie('efc_refresh_token');
   res.json({ message: 'Password changed successfully' });
 };
 `;
     await fs.outputFile(path.join(dest, "src", "api", "auth", `change-password.${ext}`), cpContent);
-    const tfaSetupMeta = mkMeta(opts, {
-      GET: {
-        description: "Generate a TOTP secret and QR code to set up 2FA.",
-        response: `{ qrCode: 'otpauth://totp/...', secret: 'BASE32SECRET' }`
-      },
-      POST: {
-        description: "Confirm a TOTP code to enable 2FA for the authenticated user.",
-        request: `{ code: '123456' }`,
-        response: `{ message: '2FA enabled' }`
-      }
-    });
-    const tfaSetupContent = ts ? `${RA}import type { Request, Response } from 'express';
-${tfaSetupMeta}${mwUser3}
-export const GET = async (req: Request, res: Response) => {
-  // TODO: generate TOTP secret and return QR code URL
-  res.json({ qrCode: 'otpauth://totp/...', secret: 'BASE32SECRET' });
-};
-
-export const POST = async (req: Request, res: Response) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify TOTP code and enable 2FA
-  res.json({ message: '2FA enabled' });
-};
-` : `${RA}${tfaSetupMeta}${mwUser3}
-export const GET = async (req, res) => {
-  // TODO: generate TOTP secret and return QR code URL
-  res.json({ qrCode: 'otpauth://totp/...', secret: 'BASE32SECRET' });
-};
-
-export const POST = async (req, res) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify TOTP code and enable 2FA
-  res.json({ message: '2FA enabled' });
-};
-`;
-    await fs.outputFile(
-      path.join(dest, "src", "api", "auth", "2fa", `setup.${ext}`),
-      tfaSetupContent
-    );
-    const tfaVerifyMeta = mkMeta(opts, {
-      POST: {
-        description: "Verify a TOTP code during login.",
-        request: `{ code: '123456' }`,
-        response: `{ message: '2FA verified' }`
-      }
-    });
-    const tfaVerifyContent = ts ? `${RA}import type { Request, Response } from 'express';
-${tfaVerifyMeta}export const POST = async (req: Request, res: Response) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify TOTP code
-  res.json({ message: '2FA verified' });
-};
-` : `${RA}${tfaVerifyMeta}export const POST = async (req, res) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify TOTP code
-  res.json({ message: '2FA verified' });
-};
-`;
-    await fs.outputFile(
-      path.join(dest, "src", "api", "auth", "2fa", `verify.${ext}`),
-      tfaVerifyContent
-    );
-    const tfaDisableMeta = mkMeta(opts, {
-      POST: {
-        description: "Disable 2FA for the authenticated user.",
-        request: `{ code: '123456' }`,
-        response: `{ message: '2FA disabled' }`
-      }
-    });
-    const tfaDisableContent = ts ? `${RA}import type { Request, Response } from 'express';
-${tfaDisableMeta}${mwUser3}
-export const POST = async (req: Request, res: Response) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify code and disable 2FA
-  res.json({ message: '2FA disabled' });
-};
-` : `${RA}${tfaDisableMeta}${mwUser3}
-export const POST = async (req, res) => {
-  const { code } = req.body;
-  if (!code) return res.status(400).json({ error: 'code is required' });
-  // TODO: verify code and disable 2FA
-  res.json({ message: '2FA disabled' });
-};
-`;
-    await fs.outputFile(
-      path.join(dest, "src", "api", "auth", "2fa", `disable.${ext}`),
-      tfaDisableContent
-    );
-    const sessListMeta = mkMeta(opts, {
-      GET: {
-        description: "List all active sessions for the authenticated user.",
-        response: `{ sessions: [] }`
-      }
-    });
-    const sessListContent = ts ? `${RA}import type { Request, Response } from 'express';
-${sessListMeta}${mwUser3}
-export const GET = async (req: Request, res: Response) => {
-  // TODO: fetch sessions for req.user.id
-  res.json({ sessions: [] });
-};
-` : `${RA}${sessListMeta}${mwUser3}
-export const GET = async (req, res) => {
-  // TODO: fetch sessions for req.user.id
-  res.json({ sessions: [] });
-};
-`;
-    await fs.outputFile(
-      path.join(dest, "src", "api", "auth", "sessions", `index.${ext}`),
-      sessListContent
-    );
-    const sessRevokeMeta = mkMeta(opts, {
-      DELETE: {
-        description: "Revoke a single active session by ID.",
-        params: `{ id: 'sess_01HXZ' }`,
-        response: `{ message: 'Session sess_01HXZ revoked' }`
-      }
-    });
-    const sessRevokeContent = ts ? `${RA}import type { Request, Response } from 'express';
-${sessRevokeMeta}${mwUser3}
-export const DELETE = async (req: Request, res: Response) => {
-  const { id } = req.params;
-  // TODO: revoke session by id
-  res.json({ message: \`Session \${id} revoked\` });
-};
-` : `${RA}${sessRevokeMeta}${mwUser3}
-export const DELETE = async (req, res) => {
-  const { id } = req.params;
-  // TODO: revoke session by id
-  res.json({ message: \`Session \${id} revoked\` });
-};
+    for (const [file, content] of Object.entries(twoFactorRoutes(ts, usesTables(opts), hasAdmin))) {
+      await fs.outputFile(path.join(dest, "src", "api", "auth", `${file}.${ext}`), content);
+    }
+    for (const endpoint of [
+      { file: "sessions/index", methods: ["GET"], feature: "Device session management" },
+      { file: "sessions/[id]", methods: ["DELETE"], feature: "Device session management" }
+    ]) {
+      const message = `${endpoint.feature} is not implemented. Connect an implementation before enabling this feature.`;
+      const metadata = mkMeta(
+        opts,
+        Object.fromEntries(
+          endpoint.methods.map((method) => [
+            method,
+            {
+              description: `${endpoint.feature} extension point (not implemented).`,
+              status: 501,
+              response: JSON.stringify({ error: message, statusCode: 501 })
+            }
+          ])
+        )
+      );
+      const handlers = endpoint.methods.map(
+        (method) => `export const ${method} = (_req${ts ? ": Request" : ""}, res${ts ? ": Response" : ""}) => {
+  res.status(501).json({ error: ${JSON.stringify(message)}, statusCode: 501 });
+};`
+      ).join("\n\n");
+      const content = `${RA}${ts ? "import type { Request, Response } from 'express';\n" : ""}${metadata}${mwUser3}
+// Extension point: replace this handler only after wiring and testing the feature.
+${handlers}
 `;
-    await fs.outputFile(
-      path.join(dest, "src", "api", "auth", "sessions", `[id].${ext}`),
-      sessRevokeContent
-    );
+      await fs.outputFile(
+        path.join(dest, "src", "api", "auth", `${endpoint.file}.${ext}`),
+        content
+      );
+    }
   }
 }
 async function writeUserExtendedRoutes(dest, opts) {
@@ -3878,6 +4105,7 @@ export async function signInWithOAuth(res${T(": Response")}, profile${T(": OAuth
     }
   }
   if (!user.isActive) throw new HttpError(403, 'Account suspended');
+  if (user.twoFactorEnabled) throw new HttpError(403, 'Use password login with an authenticator code for this account');
   // http-only: sets the cookie, returns undefined. bearer: returns the token.
   return issueToken(res, { id: user.id, role: user.role, email: user.email });
 }
@@ -4223,9 +4451,31 @@ var ITEMS = [
   {
     name: "account-security",
     title: "Account security",
-    description: "change password, 2FA, sessions, token refresh",
+    description: "password changes, TOTP or email OTP, token refresh; device-session extension points",
     group: "user",
     registryDependencies: ["auth"],
+    prompts: [
+      {
+        name: "TWO_FACTOR_METHOD",
+        type: "select",
+        message: "Two-factor authentication methods:",
+        default: "totp",
+        options: [
+          { value: "totp", label: "Authenticator app (TOTP)" },
+          {
+            value: "email",
+            label: "Email OTP",
+            hint: "requires the email-client SMTP integration"
+          },
+          {
+            value: "both",
+            label: "Both \u2014 users choose",
+            hint: "requires the email-client SMTP integration"
+          }
+        ],
+        note: "Email OTP requires efc add email-client and working SMTP settings. Each user enrolls one allowed method."
+      }
+    ],
     enable: user("accountSecurity")
   },
   {
@@ -4711,7 +4961,11 @@ async function main() {
         label: "defineTable",
         hint: "PostgreSQL-native \u2014 foreign keys, relations, include, Prisma-style queries"
       },
-      { value: "defineModel", label: "defineModel", hint: "portable \u2014 the same API on MongoDB" }
+      {
+        value: "defineModel",
+        label: "defineModel",
+        hint: "portable \u2014 the same API on MongoDB"
+      }
     ] : [
       {
         value: "defineCollection",
@@ -4769,8 +5023,20 @@ async function main() {
     required: false
   });
   if (p.isCancel(picked)) cancel2();
-  const items = withDependencies(picked);
+  let items = withDependencies(picked);
+  const twoFactorMethod = items.includes("account-security") ? await p.select({
+    message: "Two-factor authentication methods:",
+    options: [
+      { value: "totp", label: "Authenticator app (TOTP)" },
+      { value: "email", label: "Email OTP" },
+      { value: "both", label: "Both \u2014 users choose" }
+    ]
+  }) : void 0;
+  if (p.isCancel(twoFactorMethod)) cancel2();
+  if (twoFactorMethod && twoFactorMethod !== "totp")
+    items = withDependencies([...items, "email-client"]);
   const answers = auth === "none" ? {} : { authStrategy: auth };
+  if (twoFactorMethod) answers.TWO_FACTOR_METHOD = twoFactorMethod;
   const prompts = itemPrompts(items);
   for (const q of prompts) {
     if (q.name in answers || !promptApplies(q, answers)) continue;