Merge pull request #753 from mauriceboe/dev

Dev

server/src/db/migrations.ts

@@ -1772,6 +1772,26 @@ function runMigrations(db: Database.Database): void {
       try { db.exec('ALTER TABLE oauth_tokens ADD COLUMN audience TEXT'); }
       catch (err: any) { if (!err.message?.includes('duplicate column name')) throw err; }
     },
+    // Migration: password reset — add password_version for session
+    // invalidation, and a token table keyed by SHA-256 hash (raw tokens
+    // never hit the DB).
+    () => {
+      try { db.exec('ALTER TABLE users ADD COLUMN password_version INTEGER NOT NULL DEFAULT 0'); }
+      catch (err: any) { if (!err.message?.includes('duplicate column name')) throw err; }
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS password_reset_tokens (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+          token_hash TEXT NOT NULL UNIQUE,
+          expires_at DATETIME NOT NULL,
+          consumed_at DATETIME,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          created_ip TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_prt_user ON password_reset_tokens(user_id);
+        CREATE INDEX IF NOT EXISTS idx_prt_hash ON password_reset_tokens(token_hash);
+      `);
+    },
   ];
 
   if (currentVersion < migrations.length) {

server/src/db/schema.ts

@@ -25,10 +25,23 @@ function createTables(db: Database.Database): void {
       synology_password TEXT,
       synology_sid TEXT,
       must_change_password INTEGER DEFAULT 0,
+      password_version INTEGER NOT NULL DEFAULT 0,
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
       updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
     );
 
+    CREATE TABLE IF NOT EXISTS password_reset_tokens (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+      token_hash TEXT NOT NULL UNIQUE,
+      expires_at DATETIME NOT NULL,
+      consumed_at DATETIME,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      created_ip TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_prt_user ON password_reset_tokens(user_id);
+    CREATE INDEX IF NOT EXISTS idx_prt_hash ON password_reset_tokens(token_hash);
+
     CREATE TABLE IF NOT EXISTS settings (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,

server/src/middleware/auth.ts

@@ -15,11 +15,21 @@ export function extractToken(req: Request): string | null {
 
 function verifyJwtAndLoadUser(token: string): User | null {
   try {
-    const decoded = jwt.verify(token, JWT_SECRET, { algorithms: ['HS256'] }) as { id: number };
-    const user = db.prepare(
-      'SELECT id, username, email, role FROM users WHERE id = ?'
-    ).get(decoded.id) as User | undefined;
-    return user ?? null;
+    const decoded = jwt.verify(token, JWT_SECRET, { algorithms: ['HS256'] }) as { id: number; pv?: number };
+    const row = db.prepare(
+      'SELECT id, username, email, role, password_version FROM users WHERE id = ?'
+    ).get(decoded.id) as (User & { password_version?: number }) | undefined;
+    if (!row) return null;
+    // Session invalidation: any token whose embedded password_version
+    // predates the user's current one is rejected. Tokens issued before
+    // the `pv` claim existed (decoded.pv === undefined) are treated as
+    // version 0 so legacy sessions keep working until the user resets.
+    const tokenPv = typeof decoded.pv === 'number' ? decoded.pv : 0;
+    const currentPv = typeof row.password_version === 'number' ? row.password_version : 0;
+    if (tokenPv !== currentPv) return null;
+    // Don't leak password_version beyond the middleware.
+    const { password_version: _pv, ...user } = row;
+    return user as User;
   } catch {
     return null;
   }
@@ -68,15 +78,7 @@ const optionalAuth = (req: Request, res: Response, next: NextFunction): void =>
     return next();
   }
 
-  try {
-    const decoded = jwt.verify(token, JWT_SECRET, { algorithms: ['HS256'] }) as { id: number };
-    const user = db.prepare(
-      'SELECT id, username, email, role FROM users WHERE id = ?'
-    ).get(decoded.id) as User | undefined;
-    (req as OptionalAuthRequest).user = user || null;
-  } catch (err: unknown) {
-    (req as OptionalAuthRequest).user = null;
-  }
+  (req as OptionalAuthRequest).user = verifyJwtAndLoadUser(token) || null;
   next();
 };
 

server/src/routes/auth.ts

@@ -36,7 +36,10 @@ import {
   deleteMcpToken,
   createWsToken,
   createResourceToken,
+  requestPasswordReset,
+  resetPassword,
 } from '../services/authService';
+import { sendPasswordResetEmail } from '../services/notifications';
 
 const router = express.Router();
 
@@ -76,6 +79,8 @@ const RATE_LIMIT_CLEANUP = 5 * 60 * 1000;
 
 const loginAttempts = new Map<string, { count: number; first: number }>();
 const mfaAttempts = new Map<string, { count: number; first: number }>();
+const forgotAttempts = new Map<string, { count: number; first: number }>();
+const resetAttempts = new Map<string, { count: number; first: number }>();
 setInterval(() => {
   const now = Date.now();
   for (const [key, record] of loginAttempts) {
@@ -84,6 +89,12 @@ setInterval(() => {
   for (const [key, record] of mfaAttempts) {
     if (now - record.first >= RATE_LIMIT_WINDOW) mfaAttempts.delete(key);
   }
+  for (const [key, record] of forgotAttempts) {
+    if (now - record.first >= RATE_LIMIT_WINDOW) forgotAttempts.delete(key);
+  }
+  for (const [key, record] of resetAttempts) {
+    if (now - record.first >= RATE_LIMIT_WINDOW) resetAttempts.delete(key);
+  }
 }, RATE_LIMIT_CLEANUP);
 
 function rateLimiter(maxAttempts: number, windowMs: number, store = loginAttempts) {
@@ -104,6 +115,8 @@ function rateLimiter(maxAttempts: number, windowMs: number, store = loginAttempt
 }
 const authLimiter = rateLimiter(10, RATE_LIMIT_WINDOW);
 const mfaLimiter = rateLimiter(5, RATE_LIMIT_WINDOW, mfaAttempts);
+const forgotLimiter = rateLimiter(3, RATE_LIMIT_WINDOW, forgotAttempts);
+const resetLimiter = rateLimiter(5, RATE_LIMIT_WINDOW, resetAttempts);
 
 // ---------------------------------------------------------------------------
 // Routes
@@ -146,6 +159,71 @@ router.post('/login', authLimiter, (req: Request, res: Response) => {
   res.json({ token: result.token, user: result.user });
 });
 
+// ---------------------------------------------------------------------------
+// Password reset (forgot / complete)
+// ---------------------------------------------------------------------------
+
+// Generic OK response — identical regardless of email existence, to
+// prevent enumeration via response body OR status code.
+const GENERIC_FORGOT_RESPONSE = { ok: true };
+// Minimum time we spend inside the forgot handler so a "no such user"
+// path does not complete noticeably faster than a real reset.
+const FORGOT_MIN_LATENCY_MS = 350;
+
+router.post('/forgot-password', forgotLimiter, async (req: Request, res: Response) => {
+  const started = Date.now();
+  const rawEmail = typeof req.body?.email === 'string' ? req.body.email : '';
+  const ip = getClientIp(req);
+
+  const outcome = requestPasswordReset(rawEmail, ip);
+
+  if (outcome.reason === 'issued' && outcome.tokenForDelivery && outcome.userEmail) {
+    // Build the reset URL from the incoming request origin so dev /
+    // prod both work without extra config.
+    const origin = (req.headers['origin'] as string | undefined)
+      || (req.headers['referer'] ? new URL(req.headers['referer'] as string).origin : undefined)
+      || `${req.protocol}://${req.get('host')}`;
+    const url = `${origin.replace(/\/$/, '')}/reset-password?token=${encodeURIComponent(outcome.tokenForDelivery)}`;
+
+    // Audit the REQUEST always — even for "no user" — so abuse is visible.
+    writeAudit({ userId: outcome.userId, action: 'user.password_reset_request', ip, details: { delivered: 'pending' } });
+
+    try {
+      const delivery = await sendPasswordResetEmail(outcome.userEmail, url, outcome.userId);
+      writeAudit({ userId: outcome.userId, action: 'user.password_reset_request', ip, details: { delivered: delivery.delivered } });
+    } catch (err) {
+      // Never surface delivery failure to the caller — still respond ok.
+      writeAudit({ userId: outcome.userId, action: 'user.password_reset_request', ip, details: { delivered: 'failed' } });
+    }
+  } else {
+    writeAudit({ userId: outcome.userId, action: 'user.password_reset_request', ip, details: { reason: outcome.reason } });
+  }
+
+  // Pad the response so timing doesn't reveal outcome.
+  const elapsed = Date.now() - started;
+  if (elapsed < FORGOT_MIN_LATENCY_MS) {
+    await new Promise((r) => setTimeout(r, FORGOT_MIN_LATENCY_MS - elapsed));
+  }
+  res.json(GENERIC_FORGOT_RESPONSE);
+});
+
+router.post('/reset-password', resetLimiter, (req: Request, res: Response) => {
+  const ip = getClientIp(req);
+  const result = resetPassword(req.body);
+  if (result.error) {
+    writeAudit({ userId: null, action: 'user.password_reset_fail', ip, details: { reason: result.error } });
+    return res.status(result.status!).json({ error: result.error });
+  }
+  if (result.mfa_required) {
+    return res.status(200).json({ mfa_required: true });
+  }
+  writeAudit({ userId: result.userId ?? null, action: 'user.password_reset_success', ip });
+  // Purposefully do NOT auto-login — the user just demonstrated they
+  // have email+password access; asking them to sign in fresh is the
+  // standard, safer UX.
+  res.json({ success: true });
+});
+
 router.get('/me', authenticate, (req: Request, res: Response) => {
   const authReq = req as AuthRequest;
   const user = getCurrentUser(authReq.user.id);

server/src/services/authService.ts

@@ -156,9 +156,12 @@ export function isOidcOnlyMode(): boolean {
   return !resolveAuthToggles().password_login;
 }
 
-export function generateToken(user: { id: number | bigint }) {
+export function generateToken(user: { id: number | bigint; password_version?: number }) {
+  const pv = typeof user.password_version === 'number'
+    ? user.password_version
+    : ((db.prepare('SELECT password_version FROM users WHERE id = ?').get(user.id) as { password_version?: number } | undefined)?.password_version ?? 0);
   return jwt.sign(
-    { id: user.id },
+    { id: user.id, pv },
     JWT_SECRET,
     { expiresIn: '24h', algorithm: 'HS256' }
   );
@@ -994,6 +997,210 @@ export function verifyMfaLogin(body: {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Password reset
+// ---------------------------------------------------------------------------
+
+// 60 min; long enough to read the email in a second tab, short enough
+// that a leaked link is unlikely to still be valid when someone tries it.
+const PASSWORD_RESET_TTL_MS = 60 * 60 * 1000;
+const PASSWORD_RESET_TOKEN_BYTES = 32; // 256-bit entropy
+
+/**
+ * Returns the SHA-256 hex hash of a reset token. Raw tokens are never
+ * persisted — we only store and compare their hashes.
+ */
+function hashResetToken(raw: string): string {
+  return createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * Shape returned by requestPasswordReset. For enumeration-safety the
+ * route ALWAYS returns the same response to the client regardless of
+ * whether a user existed — this struct is only consumed internally by
+ * the route handler to decide whether to send an email / log a link.
+ */
+export interface PasswordResetRequestOutcome {
+  tokenForDelivery: string | null;   // raw token — send via email or log, never return to client
+  userId: number | null;
+  userEmail: string | null;
+  reason: 'issued' | 'no_user' | 'oidc_only' | 'throttled_per_email' | 'password_login_disabled';
+}
+
+// Per-email throttle (defence-in-depth on top of the per-IP limiter).
+const perEmailResetAttempts = new Map<string, { count: number; first: number }>();
+const PASSWORD_RESET_PER_EMAIL_WINDOW_MS = 15 * 60 * 1000;
+const PASSWORD_RESET_PER_EMAIL_MAX = 3;
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, record] of perEmailResetAttempts) {
+    if (now - record.first >= PASSWORD_RESET_PER_EMAIL_WINDOW_MS) perEmailResetAttempts.delete(key);
+  }
+}, 5 * 60 * 1000).unref?.();
+
+export function requestPasswordReset(rawEmail: string, createdIp: string | null): PasswordResetRequestOutcome {
+  const email = String(rawEmail || '').trim().toLowerCase();
+  // Basic shape check — a fully empty / malformed email is treated like
+  // "no user" so we still spend the same time internally.
+  const looksLikeEmail = email.length > 0 && /.+@.+\..+/.test(email);
+
+  // Global policy check: password login disabled → no reset possible.
+  const toggles = resolveAuthToggles();
+  if (!toggles.password_login) {
+    return { tokenForDelivery: null, userId: null, userEmail: null, reason: 'password_login_disabled' };
+  }
+
+  // Per-email throttle. We check this BEFORE the DB lookup so the timing
+  // is identical regardless of whether the account exists.
+  const throttleKey = email || '__noemail__';
+  const now = Date.now();
+  const record = perEmailResetAttempts.get(throttleKey);
+  if (record && record.count >= PASSWORD_RESET_PER_EMAIL_MAX && now - record.first < PASSWORD_RESET_PER_EMAIL_WINDOW_MS) {
+    return { tokenForDelivery: null, userId: null, userEmail: null, reason: 'throttled_per_email' };
+  }
+  if (!record || now - record.first >= PASSWORD_RESET_PER_EMAIL_WINDOW_MS) {
+    perEmailResetAttempts.set(throttleKey, { count: 1, first: now });
+  } else {
+    record.count++;
+  }
+
+  if (!looksLikeEmail) {
+    return { tokenForDelivery: null, userId: null, userEmail: null, reason: 'no_user' };
+  }
+
+  const user = db.prepare('SELECT id, email, password_hash, oidc_sub FROM users WHERE email = ?').get(email) as
+    | { id: number; email: string; password_hash: string | null; oidc_sub: string | null }
+    | undefined;
+
+  if (!user) {
+    return { tokenForDelivery: null, userId: null, userEmail: null, reason: 'no_user' };
+  }
+  // OIDC-only account (no local password) — we can't reset what isn't there.
+  // The client still gets the generic "if that email exists…" response.
+  if (!user.password_hash && user.oidc_sub) {
+    return { tokenForDelivery: null, userId: user.id, userEmail: user.email, reason: 'oidc_only' };
+  }
+
+  // Invalidate any prior unconsumed tokens for this user so there is
+  // always at most one live reset link in flight.
+  db.prepare(
+    "UPDATE password_reset_tokens SET consumed_at = CURRENT_TIMESTAMP WHERE user_id = ? AND consumed_at IS NULL"
+  ).run(user.id);
+
+  const raw = randomBytes(PASSWORD_RESET_TOKEN_BYTES).toString('base64url');
+  const token_hash = hashResetToken(raw);
+  const expires_at = new Date(Date.now() + PASSWORD_RESET_TTL_MS).toISOString();
+
+  db.prepare(
+    'INSERT INTO password_reset_tokens (user_id, token_hash, expires_at, created_ip) VALUES (?, ?, ?, ?)'
+  ).run(user.id, token_hash, expires_at, createdIp);
+
+  return { tokenForDelivery: raw, userId: user.id, userEmail: user.email, reason: 'issued' };
+}
+
+export interface ResetPasswordOutcome {
+  error?: string;
+  status?: number;
+  success?: boolean;
+  /** When true the client must collect a TOTP/backup code and call again. */
+  mfa_required?: boolean;
+  userId?: number;
+}
+
+/**
+ * Consume a reset token and set a new password. If the target user has
+ * MFA enabled, a valid TOTP code or backup code must be supplied — a
+ * compromised email alone therefore does NOT allow taking over a
+ * 2FA-protected account.
+ */
+export function resetPassword(body: {
+  token?: string;
+  new_password?: string;
+  mfa_code?: string;
+}): ResetPasswordOutcome {
+  const { token, new_password, mfa_code } = body;
+  if (!token || typeof token !== 'string') {
+    return { error: 'Reset token is required', status: 400 };
+  }
+  if (!new_password || typeof new_password !== 'string') {
+    return { error: 'New password is required', status: 400 };
+  }
+  // Check the policy BEFORE touching the token so an invalid password
+  // does not burn the user's one-time link.
+  const pwCheck = validatePassword(new_password);
+  if (!pwCheck.ok) return { error: pwCheck.reason!, status: 400 };
+
+  const tokenHash = hashResetToken(token);
+  const row = db.prepare(
+    'SELECT id, user_id, expires_at, consumed_at FROM password_reset_tokens WHERE token_hash = ?'
+  ).get(tokenHash) as
+    | { id: number; user_id: number; expires_at: string; consumed_at: string | null }
+    | undefined;
+
+  if (!row) return { error: 'Invalid or expired reset link', status: 400 };
+  if (row.consumed_at) return { error: 'This reset link has already been used', status: 400 };
+  if (new Date(row.expires_at).getTime() < Date.now()) {
+    return { error: 'Reset link has expired. Please request a new one.', status: 400 };
+  }
+
+  const user = db.prepare(
+    'SELECT id, email, mfa_enabled, mfa_secret, mfa_backup_codes, password_version FROM users WHERE id = ?'
+  ).get(row.user_id) as
+    | { id: number; email: string; mfa_enabled: number | boolean; mfa_secret: string | null; mfa_backup_codes: string | null; password_version: number }
+    | undefined;
+
+  if (!user) return { error: 'Invalid or expired reset link', status: 400 };
+
+  // MFA gate. If enabled, require a valid TOTP or backup code.
+  const mfaOn = user.mfa_enabled === 1 || user.mfa_enabled === true;
+  let backupCodeConsumedIndex: number | null = null;
+  if (mfaOn) {
+    if (!user.mfa_secret) {
+      // Data inconsistency — fail closed.
+      return { error: 'MFA is enabled but not configured. Contact your administrator.', status: 500 };
+    }
+    const supplied = typeof mfa_code === 'string' ? mfa_code.trim() : '';
+    if (!supplied) return { mfa_required: true, status: 200 };
+
+    const secret = decryptMfaSecret(user.mfa_secret);
+    const okTotp = authenticator.verify({ token: supplied.replace(/\s/g, ''), secret });
+    if (!okTotp) {
+      const hashes = parseBackupCodeHashes(user.mfa_backup_codes);
+      const candidateHash = hashBackupCode(supplied);
+      const idx = hashes.findIndex(h => h === candidateHash);
+      if (idx === -1) return { error: 'Invalid MFA code', status: 401 };
+      backupCodeConsumedIndex = idx;
+    }
+  }
+
+  const newHash = bcrypt.hashSync(new_password, 12);
+  const newPv = (user.password_version ?? 0) + 1;
+
+  db.transaction(() => {
+    // Burn the token first to keep it atomic with the password change.
+    db.prepare('UPDATE password_reset_tokens SET consumed_at = CURRENT_TIMESTAMP WHERE id = ?').run(row.id);
+    // Also burn every OTHER live token for this user — a fresh login
+    // should not leave a second door open.
+    db.prepare(
+      "UPDATE password_reset_tokens SET consumed_at = CURRENT_TIMESTAMP WHERE user_id = ? AND consumed_at IS NULL AND id != ?"
+    ).run(user.id, row.id);
+    db.prepare(
+      'UPDATE users SET password_hash = ?, must_change_password = 0, password_version = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?'
+    ).run(newHash, newPv, user.id);
+    // Consume backup code if one was used.
+    if (backupCodeConsumedIndex !== null) {
+      const hashes = parseBackupCodeHashes(user.mfa_backup_codes);
+      hashes.splice(backupCodeConsumedIndex, 1);
+      db.prepare('UPDATE users SET mfa_backup_codes = ? WHERE id = ?').run(JSON.stringify(hashes), user.id);
+    }
+  })();
+
+  // Kick off any MCP/WS session cleanup — same hook the account-delete path uses.
+  try { revokeUserSessions?.(user.id); } catch { /* best-effort */ }
+
+  return { success: true, userId: user.id };
+}
+
 // ---------------------------------------------------------------------------
 // MCP tokens
 // ---------------------------------------------------------------------------

server/src/services/notifications.ts

@@ -316,6 +316,103 @@ export function buildEmailHtml(subject: string, body: string, lang: string, navi
 
 // ── Send functions ─────────────────────────────────────────────────────────
 
+// ── Password reset email ───────────────────────────────────────────────────
+
+interface PasswordResetStrings { subject: string; greeting: string; body: string; ctaIntro: string; expiry: string; ignore: string }
+
+const PASSWORD_RESET_I18N: Record<string, PasswordResetStrings> = {
+  en: { subject: 'Reset your password', greeting: 'Hi', body: 'We received a request to reset the password for your TREK account. Click the button below to set a new password.', ctaIntro: 'Reset password', expiry: 'This link expires in 60 minutes.', ignore: "If you didn't request this, you can safely ignore this email — your password won't change." },
+  de: { subject: 'Passwort zurücksetzen', greeting: 'Hallo', body: 'Wir haben eine Anfrage erhalten, das Passwort für dein TREK-Konto zurückzusetzen. Klicke auf den Button unten, um ein neues Passwort festzulegen.', ctaIntro: 'Passwort zurücksetzen', expiry: 'Dieser Link ist 60 Minuten gültig.', ignore: 'Wenn du das nicht warst, ignoriere diese E-Mail — dein Passwort bleibt unverändert.' },
+  fr: { subject: 'Réinitialisez votre mot de passe', greeting: 'Bonjour', body: 'Nous avons reçu une demande de réinitialisation du mot de passe de votre compte TREK. Cliquez sur le bouton ci-dessous pour définir un nouveau mot de passe.', ctaIntro: 'Réinitialiser le mot de passe', expiry: 'Ce lien expire dans 60 minutes.', ignore: "Si vous n'êtes pas à l'origine de cette demande, ignorez cet e-mail — votre mot de passe ne changera pas." },
+  es: { subject: 'Restablecer tu contraseña', greeting: 'Hola', body: 'Recibimos una solicitud para restablecer la contraseña de tu cuenta de TREK. Haz clic en el botón de abajo para establecer una nueva contraseña.', ctaIntro: 'Restablecer contraseña', expiry: 'Este enlace caduca en 60 minutos.', ignore: 'Si no solicitaste esto, puedes ignorar este correo — tu contraseña no cambiará.' },
+  it: { subject: 'Reimposta la tua password', greeting: 'Ciao', body: 'Abbiamo ricevuto una richiesta di reimpostazione della password per il tuo account TREK. Clicca il pulsante qui sotto per impostare una nuova password.', ctaIntro: 'Reimposta password', expiry: 'Questo link scade tra 60 minuti.', ignore: 'Se non hai richiesto questa operazione, ignora questa email — la tua password non cambierà.' },
+  nl: { subject: 'Reset je wachtwoord', greeting: 'Hallo', body: 'We hebben een verzoek ontvangen om het wachtwoord voor je TREK-account te resetten. Klik op de knop hieronder om een nieuw wachtwoord in te stellen.', ctaIntro: 'Wachtwoord resetten', expiry: 'Deze link verloopt over 60 minuten.', ignore: 'Als jij dit niet hebt aangevraagd, kun je deze e-mail negeren — je wachtwoord blijft ongewijzigd.' },
+  ru: { subject: 'Сброс пароля', greeting: 'Здравствуйте', body: 'Мы получили запрос на сброс пароля вашего аккаунта TREK. Нажмите кнопку ниже, чтобы установить новый пароль.', ctaIntro: 'Сбросить пароль', expiry: 'Ссылка действительна 60 минут.', ignore: 'Если вы не запрашивали сброс — просто проигнорируйте это письмо, пароль останется прежним.' },
+  zh: { subject: '重置您的密码', greeting: '您好', body: '我们收到了重置您的 TREK 账户密码的请求。点击下方按钮设置新密码。', ctaIntro: '重置密码', expiry: '此链接将在 60 分钟后失效。', ignore: '如果这不是您本人的请求，可以忽略本邮件 — 您的密码不会改变。' },
+  'zh-TW': { subject: '重設您的密碼', greeting: '您好', body: '我們收到了重設您 TREK 帳號密碼的請求。點擊下方按鈕以設定新密碼。', ctaIntro: '重設密碼', expiry: '此連結將於 60 分鐘後失效。', ignore: '若非您本人發起的請求，請忽略此郵件 — 您的密碼不會變更。' },
+  hu: { subject: 'Jelszó visszaállítása', greeting: 'Szia', body: 'Kérést kaptunk a TREK-fiókod jelszavának visszaállítására. Kattints az alábbi gombra az új jelszó beállításához.', ctaIntro: 'Jelszó visszaállítása', expiry: 'Ez a link 60 perc után lejár.', ignore: 'Ha nem te kérted ezt, nyugodtan hagyd figyelmen kívül ezt az e-mailt — a jelszavad változatlan marad.' },
+  ar: { subject: 'إعادة تعيين كلمة المرور', greeting: 'مرحبا', body: 'تلقينا طلبًا لإعادة تعيين كلمة المرور لحسابك في TREK. انقر على الزر أدناه لتعيين كلمة مرور جديدة.', ctaIntro: 'إعادة تعيين كلمة المرور', expiry: 'تنتهي صلاحية هذا الرابط خلال 60 دقيقة.', ignore: 'إذا لم تطلب هذا، يمكنك تجاهل هذه الرسالة — لن تتغير كلمة المرور الخاصة بك.' },
+  br: { subject: 'Redefinir sua senha', greeting: 'Olá', body: 'Recebemos um pedido para redefinir a senha da sua conta TREK. Clique no botão abaixo para definir uma nova senha.', ctaIntro: 'Redefinir senha', expiry: 'Este link expira em 60 minutos.', ignore: 'Se você não solicitou isto, pode ignorar este e-mail — sua senha não será alterada.' },
+  cs: { subject: 'Obnovení hesla', greeting: 'Ahoj', body: 'Obdrželi jsme žádost o obnovení hesla k tvému účtu TREK. Klikni na tlačítko níže a nastav nové heslo.', ctaIntro: 'Obnovit heslo', expiry: 'Odkaz vyprší za 60 minut.', ignore: 'Pokud jsi o obnovení nežádal/a, tento e-mail ignoruj — heslo zůstane beze změny.' },
+  pl: { subject: 'Zresetuj hasło', greeting: 'Cześć', body: 'Otrzymaliśmy prośbę o zresetowanie hasła do Twojego konta TREK. Kliknij przycisk poniżej, aby ustawić nowe hasło.', ctaIntro: 'Zresetuj hasło', expiry: 'Link wygaśnie za 60 minut.', ignore: 'Jeśli to nie Ty, zignoruj tę wiadomość — Twoje hasło pozostanie bez zmian.' },
+};
+
+function buildPasswordResetHtml(subject: string, strings: PasswordResetStrings, recipient: string, resetUrl: string, lang: string): string {
+  const safeGreeting = escapeHtml(`${strings.greeting}, ${recipient}`);
+  const safeBody = escapeHtml(strings.body);
+  const safeExpiry = escapeHtml(strings.expiry);
+  const safeIgnore = escapeHtml(strings.ignore);
+  const safeCta = escapeHtml(strings.ctaIntro);
+  const block = `
+    <p style="margin:0 0 16px 0; font-size:16px;">${safeGreeting},</p>
+    <p style="margin:0 0 20px 0; font-size:15px; line-height:1.6;">${safeBody}</p>
+    <p style="margin:28px 0;">
+      <a href="${resetUrl}" style="display:inline-block;padding:14px 28px;background:#111827;color:#fff;text-decoration:none;border-radius:10px;font-weight:600;font-size:15px;">${safeCta}</a>
+    </p>
+    <p style="margin:0 0 10px 0; font-size:13px; color:#6B7280;">${safeExpiry}</p>
+    <p style="margin:0; font-size:13px; color:#6B7280;">${safeIgnore}</p>
+  `;
+  return buildEmailHtml(subject, block, lang);
+}
+
+/**
+ * Delivers a password-reset link. When SMTP is configured the user
+ * receives an email. When it isn't, the link is logged to stdout in a
+ * clearly-fenced block so the self-hosting admin can hand it off by
+ * other means. In both cases the caller always gets a boolean that
+ * indicates only whether the caller should treat delivery as
+ * best-effort done — the API response to the user must NOT leak it.
+ */
+export async function sendPasswordResetEmail(
+  to: string,
+  resetUrl: string,
+  userId: number | null,
+): Promise<{ delivered: 'email' | 'log' | 'failed' }> {
+  const lang = userId ? getUserLanguage(userId) : 'en';
+  const strings = PASSWORD_RESET_I18N[lang] || PASSWORD_RESET_I18N.en;
+  const smtpCfg = getSmtpConfig();
+
+  if (!smtpCfg) {
+    // No SMTP configured — log the link in a visually distinct block so
+    // the admin can relay it. Never log the associated user id/email
+    // content at a lower level, only what's needed.
+    // eslint-disable-next-line no-console
+    console.log(
+      `\n===== PASSWORD RESET LINK =====\n` +
+      `to: ${to}\n` +
+      `url: ${resetUrl}\n` +
+      `expires: 60 minutes\n` +
+      `(SMTP is not configured — deliver this link to the user manually.)\n` +
+      `================================\n`,
+    );
+    logInfo(`Password reset link issued (no SMTP) for=${to}`);
+    return { delivered: 'log' };
+  }
+
+  try {
+    const skipTls = process.env.SMTP_SKIP_TLS_VERIFY === 'true' || getAppSetting('smtp_skip_tls_verify') === 'true';
+    const transporter = nodemailer.createTransport({
+      host: smtpCfg.host,
+      port: smtpCfg.port,
+      secure: smtpCfg.secure,
+      auth: smtpCfg.user ? { user: smtpCfg.user, pass: smtpCfg.pass } : undefined,
+      ...(skipTls ? { tls: { rejectUnauthorized: false } } : {}),
+    });
+    await transporter.sendMail({
+      from: smtpCfg.from,
+      to,
+      subject: `TREK — ${strings.subject}`,
+      text: `${strings.greeting}, ${to}\n\n${strings.body}\n\n${strings.ctaIntro}: ${resetUrl}\n\n${strings.expiry}\n${strings.ignore}`,
+      html: buildPasswordResetHtml(strings.subject, strings, to, resetUrl, lang),
+    });
+    logInfo(`Password reset email sent to=${to}`);
+    return { delivered: 'email' };
+  } catch (err) {
+    logError(`Password reset email failed to=${to}: ${err instanceof Error ? err.message : err}`);
+    return { delivered: 'failed' };
+  }
+}
+
 export async function sendEmail(to: string, subject: string, body: string, userId?: number, navigateTarget?: string): Promise<boolean> {
   const config = getSmtpConfig();
   if (!config) return false;