Восстановление пароля и письмо, которое обязано дойти

Пока ссылка восстановления жива, она и есть пароль, только хранится не в голове у человека, а там, куда он не заглядывает: во входящих, в истории браузера, в журналах почтовой службы, в пересланном письме — и в отчётах счётчика, если тот не маскирует значение token (у автора маскирует: одноразовому секрету нечего делать в аналитике и в вебвизоре). Ведёт ссылка на страницу веба /reset-password?token=…, а процедур две: forgotPassword принимает адрес и отправляет письмо, resetPassword принимает токен из ссылки и новый пароль.

Что положить в ссылку, кажется очевидным: токен из прошлой статьи. sub пользователя, срок в час, подпись секретом сервера — подделать нельзя, жизнь ограничена. Проверим, чего такой токен не умеет. Аня сбрасывает пароль по ссылке, а через полчаса ту же ссылку открывает человек, нашедший её в истории браузера на общем компьютере. В подложке — PBKDF2 из статьи про пароли и подпись HS256 из статьи про токен. Прогноз: что ответит второй переход и войдёт ли Аня своим новым паролем?

declare const SECRET: string;
declare function hashPassword(password: string): Promise<string>;
declare function verifyPassword(password: string, stored: string): Promise<boolean>;
declare function signToken(secret: string, claims: object): Promise<string>;
declare function verifyToken(secret: string, token: string, now: number): Promise<{ sub: string } | null>;

interface User {
  id: string;
  passwordHash: string;
}

const HOUR = 60 * 60;
const users = new Map<string, User>();

// ссылка из письма — токен того же вида, что при входе, только живёт час
function resetToken(user: User, now: number): Promise<string> {
  return signToken(SECRET, { sub: user.id, iat: now, exp: now + HOUR });
}

async function resetPassword(token: string, password: string, now: number): Promise<string> {
  const claims = await verifyToken(SECRET, token, now);
  const user = claims ? users.get(claims.sub) : undefined;
  if (!user) return "ссылка недействительна";
  user.passwordHash = await hashPassword(password);
  return "пароль сменён";
}

async function main() {
  const anya: User = { id: "7f3c2a9e-5b1d-4e8f-a6c0-2d9b8e1f4a37", passwordHash: await hashPassword("qwerty123") };
  users.set(anya.id, anya);
  const nine = Date.UTC(2026, 8, 15, 9, 0, 0) / 1000;
  const link = await resetToken(anya, nine);

  console.log("09:10 Аня по ссылке →", await resetPassword(link, "Кот-на-крыше-1987", nine + 10 * 60));
  // ссылка осталась в истории браузера на общем компьютере
  console.log("09:40 та же ссылка →", await resetPassword(link, "пароль-того-кто-нашёл", nine + 40 * 60));
  console.log("Аня входит новым паролем:", await verifyPassword("Кот-на-крыше-1987", anya.passwordHash));
  console.log("10:10 та же ссылка →", await resetPassword(link, "ещё-один-пароль", nine + 70 * 60));
}

main();

Второй переход сменил пароль ещё раз, и Аня осталась снаружи. Подпись верная, срок не вышел — проверке не за что отказать. Это то самое свойство, из-за которого нельзя отозвать токен входа («Срок: подпись не стареет»): выданного сервер не помнит, и верная подпись верна до exp. Для токена входа это компромисс, для ссылки восстановления — дыра. Ссылка нужна на один переход, а живёт час, и весь этот час ею может воспользоваться любой, к кому она попала. В 10:10 отказ пришёл, но это не одноразовость, а просто срок.

Одноразовость требует, чтобы после перехода что-то изменилось, и проверка это заметила. Обычный путь — вернуть серверу память: таблица выданных ссылок с пометкой «использована». API автора обходится без таблицы. Ссылку оно подписывает секретом, который меняется сам, как только ссылка сделала своё дело.

Ссылка восстановления — пароль, который сервер сам разослал по почте. Всё, что сказано о паролях, относится и к ней, пока она жива.

Что меняет сброс пароля? Хеш в строке пользователя. Если секрет подписи ссылки зависит от этого хеша, ссылка проверяется, только пока хеш прежний: первый же сброс даёт новый хеш, а с ним и новый секрет, которым старую подпись уже не проверить. У автора секрет ссылки — строка из общего секрета приложения, слова password-reset и текущего хеша пароля.

Проверке теперь нужен хеш, а он лежит у пользователя, которого называет сам токен. Поэтому sub сначала читается из нагрузки без проверки подписи, как делает jwt.decode у автора, и нужен только затем, чтобы достать строку из базы. Никаких решений по этому значению не принимается: выдуманный sub приведёт к хешу чужого пользователя, но подписи, которая сойдётся с этим хешем, у злоумышленника нет — общего секрета он не знает.

Письмо долго не приходило, и Аня попросила ссылку второй раз. Пароль она сбрасывает по второй, а через полчаса обе ссылки пробует тот, кто нашёл их в истории. Прогноз: годны ли обе ссылки до сброса и что ответит каждый переход после него?

declare const SECRET: string;
declare function hashPassword(password: string): Promise<string>;
declare function signToken(secret: string, claims: object): Promise<string>;
declare function verifyToken(secret: string, token: string, now: number): Promise<{ sub: string } | null>;
declare function textFromBase64Url(part: string): string;

interface User {
  id: string;
  passwordHash: string;
}

const HOUR = 60 * 60;
const users = new Map<string, User>();

// нагрузка без проверки подписи — как jwt.decode
function peekClaims(token: string): { sub?: unknown } | null {
  try {
    return JSON.parse(textFromBase64Url(token.split(".")[1]));
  } catch {
    return null;
  }
}

// секрет подписи зависит от текущего хеша: сменился хеш — сменился и секрет
const resetSecret = (user: User) => `${SECRET}:password-reset:${user.passwordHash}`;

function resetToken(user: User, now: number): Promise<string> {
  return signToken(resetSecret(user), { sub: user.id, iat: now, exp: now + HOUR });
}

async function userByLink(token: string, now: number): Promise<User | null> {
  // sub из непроверенного токена нужен только затем, чтобы достать хеш и уже им проверить подпись
  const sub = peekClaims(token)?.sub;
  const user = typeof sub === "string" ? users.get(sub) : undefined;
  if (!user || !(await verifyToken(resetSecret(user), token, now))) return null;
  return user;
}

async function resetPassword(token: string, password: string, now: number): Promise<string> {
  const user = await userByLink(token, now);
  if (!user) return "ссылка недействительна";
  user.passwordHash = await hashPassword(password);
  return "пароль сменён";
}

async function main() {
  const anya: User = { id: "7f3c2a9e-5b1d-4e8f-a6c0-2d9b8e1f4a37", passwordHash: await hashPassword("qwerty123") };
  users.set(anya.id, anya);
  const nine = Date.UTC(2026, 8, 15, 9, 0, 0) / 1000;
  // письмо долго не приходило, и Аня попросила ссылку второй раз
  const first = await resetToken(anya, nine);
  const second = await resetToken(anya, nine + 5 * 60);

  const valid = async (token: string) => (await userByLink(token, nine + 6 * 60)) !== null;
  console.log("09:06 первая годна:", await valid(first), "| вторая годна:", await valid(second));
  console.log("09:10 Аня по второй ссылке →", await resetPassword(second, "Кот-на-крыше-1987", nine + 10 * 60));
  console.log("09:40 вторая ещё раз →", await resetPassword(second, "пароль-того-кто-нашёл", nine + 40 * 60));
  console.log("09:41 первая →", await resetPassword(first, "пароль-того-кто-нашёл", nine + 41 * 60));
}

main();

До сброса годны обе ссылки: секрет зависит от хеша, а не от времени выдачи, и вторая ссылка первую не отменила. Сброс по второй поменял хеш, и перестали проверяться обе разом — и та, по которой перешли, и та, которую никто не трогал. Одноразовость получилась без единой записи о выданных ссылках.

Гасит ссылки любая смена хеша, не только сброс: смена пароля в настройках, перехеширование на новую стоимость при входе («Строка, которая помнит свою стоимость») и даже сброс на тот же самый пароль. Соль при каждом хешировании новая, и строка хеша выходит другой. Последнее проверено на коде автора с bcryptjs: после сброса на прежний пароль ссылка, выданная до него, получает RESET_TOKEN_INVALID.

Производный секрет заодно разводит виды токенов. Токен входа подписан общим секретом, ссылка — производным от него, поэтому ссылку не предъявить вместо токена входа, а токен входа не откроет сброс: подпись не сойдётся ни в одну сторону. Это второе средство из задачи «Ссылка из письма открывает API» — разные секреты для разных видов токенов. А слово password-reset отделит этот секрет от следующего производного, если у приложения появится, скажем, ссылка подтверждения адреса.

Одноразовость — не флажок «использована», а условие, которое перестаёт выполняться после использования. Хеш пароля меняется ровно тогда, когда ссылка сделала своё дело.

Форма восстановления принимает любой адрес и потому легко становится справочником: ввёл адрес — узнал, зарегистрирован ли он. Список адресов пригодится для подбора паролей и для писем, которые притворяются вашим сервисом, а на некоторых сайтах сам факт регистрации уже тайна. OWASP в памятке Forgot Password Cheat Sheet ставит первыми два правила: одно и то же сообщение для существующих и несуществующих учёток и одинаковое время ответа. У автора forgotPassword на любой адрес отвечает { ok: true }, а для неизвестного просто не шлёт письма.

С текстом справиться легко, со временем труднее. Вход выдавал себя стоимостью хеша, и там спасала сверка с хешем-пустышкой (задача «Вход подсказывает, есть ли такой адрес»). Здесь дорогая работа другая — письмо. Отправка — это разговор по сети с почтовым сервером, который пересылает письмо дальше, с релеем: соединение, приветствие, несколько команд. И ведётся этот разговор только для зарегистрированных адресов. Ниже два обработчика, один ждёт отправки, другой нет. Релей в примере лежит: соединение висит 300 мс и рвётся. Прогноз: что увидит тот, кто вводит в форму nobody@mail.ru и anya@mail.ru?

const registered = new Set(["anya@mail.ru"]);
const journal: string[] = [];
// отправки, которых обработчик не ждёт; пример дожидается их только ради печати журнала
const background: Promise<void>[] = [];

// почтовый релей лёг: соединение висит 300 мс и рвётся
async function sendResetMail(to: string): Promise<void> {
  await new Promise((resolve) => setTimeout(resolve, 300));
  throw new Error(`релей не ответил, письмо на ${to} не ушло`);
}

async function forgotWaits(email: string): Promise<{ ok: true }> {
  if (registered.has(email)) await sendResetMail(email);
  return { ok: true };
}

async function forgotDetached(email: string): Promise<{ ok: true }> {
  if (registered.has(email)) {
    background.push(sendResetMail(email).catch((error: Error) => { journal.push(error.message); }));
  }
  return { ok: true };
}

type Handler = (email: string) => Promise<{ ok: true }>;

// так ответ видит тот, кто вводит адреса в форму: код и время
async function request(handler: Handler, email: string): Promise<{ status: number; ms: number }> {
  const start = performance.now();
  try {
    await handler(email);
    return { status: 200, ms: performance.now() - start };
  } catch {
    return { status: 500, ms: performance.now() - start };
  }
}

async function main() {
  const handlers: [string, Handler][] = [
    ["ждёт письмо", forgotWaits],
    ["не ждёт письма", forgotDetached],
  ];
  for (const [name, handler] of handlers) {
    const nobody = await request(handler, "nobody@mail.ru");
    const anya = await request(handler, "anya@mail.ru");
    const slower = anya.ms - nobody.ms > 100 ? "да" : "нет";
    console.log(`${name} | nobody: ${nobody.status}, anya: ${anya.status} | anya медленнее nobody больше чем на 100 мс: ${slower}`);
  }
  await Promise.all(background);
  console.log("журнал сервера:", journal.join("; "));
}

main();

Обработчик, который ждёт письмо, выдал регистрацию дважды: известный адрес ответил 500, неизвестный — 200, и известный отвечал дольше на всё время разговора с релеем. Исправный релей убрал бы только первую подсказку, время разговора осталось бы. Второй обработчик ответил одинаково и кодом, и временем, а неудача отправки легла в журнал сервера — туда, где её увидит тот, кому положено. Асинхронный вызов OWASP и называет первым способом выровнять время.

У автора так и сделано. forgotPassword запускает отправку через void и не ждёт её, MailService ловит ошибку sendMail сам и пишет её в журнал, а в самом forgotPassword на промис всё равно повешен .catch. Зачем второй обработчик ошибки при первом, покажет прогон в следующем разделе.

У той же формы есть второй способ навредить — завалить чужой ящик: сто просьб о сбросе, и у жертвы сто писем, об этом в памятке OWASP написано прямо. У автора два ограничения, и отвечают они на разные вопросы. Ограничитель частоты на гостевых процедурах пропускает не больше 10 вызовов в минуту на пару «процедура + адрес клиента» (Middleware tRPC вместо guard: где ломается пайплайн Nest) — он бережёт сервер. Минутная пауза на каждого пользователя бережёт его ящик: письмо ему не уйдёт чаще раза в минуту, откуда бы ни просили. И пауза молчит: второй запрос в ту же минуту получает тот же { ok: true }, что и первый.

По ответу формы восстановления не должно быть видно ничего, кроме того, что запрос принят. Текст, код, время и пауза — четыре способа проговориться.

Не ждать письма — не значит о нём забыть. Отправка, которую никто не ждёт, по-прежнему держит сокет и память, и держит ровно столько, сколько позволят таймауты. На разговор с релеем у nodemailer их три, и в версии 10.0.10 по умолчанию это две минуты на установку соединения (connectionTimeout), 30 секунд на приветствие сервера после неё (greetingTimeout) и десять минут простоя сокета (socketTimeout). Релей, который принял соединение и замолчал, при умолчаниях держит каждую отправку полминуты. Автор ставит 5, 5 и 10 секунд: письмо восстановления не срочное, не дозвонились — пишем в журнал.

Прогон поднимает такой релей на node:net: соединение принимает, ни байта не шлёт. Сначала отправка с одним connectionTimeout в 300 мс — таймаутом, который первым приходит в голову «от зависаний». Потом транспорт со всеми тремя таймаутами, укороченными до долей секунды, и обработчик, как у автора: письма не ждёт, ошибку ловит в .catch. И последним — тот же обработчик без .catch. Прогноз: где будет письмо через секунду в первом случае и чем кончится последний?

import { createServer } from 'node:net';
import { createTransport } from 'nodemailer';

// почтовый релей, который принимает соединение и молчит, — так выглядит зависший сервер
const relay = createServer(() => {});
await new Promise((resolve) => relay.listen(0, '127.0.0.1', resolve));
const { port } = relay.address();
console.log(`релей 127.0.0.1:${port}: соединение принимает, приветствия не шлёт`);

const registered = new Set(['anya@mail.ru']);
const letter = (to) => ({
  from: 'Приложение <noreply@app.local>',
  to,
  subject: 'Восстановление пароля',
  text: 'Чтобы задать новый пароль, откройте ссылку: https://app.example/reset-password?token=…',
});

// таймаут только на соединение
const connectOnly = createTransport({ host: '127.0.0.1', port, connectionTimeout: 300 });
let state = 'ещё в пути';
connectOnly.sendMail(letter('anya@mail.ru')).then(
  () => (state = 'ушло'),
  (err) => (state = `не ушло: ${err.message}`),
);
await new Promise((resolve) => setTimeout(resolve, 1000));
console.log('только connectionTimeout: 300 — через секунду письмо', state);
connectOnly.close();

// все три таймаута, как в API автора, только короче
const transport = createTransport({
  host: '127.0.0.1',
  port,
  connectionTimeout: 300,
  greetingTimeout: 300,
  socketTimeout: 600,
});

// отправки, которых обработчик не ждёт; здесь их дожидается только печать журнала
const background = [];

function forgotPassword(email) {
  if (registered.has(email)) {
    const sending = transport
      .sendMail(letter(email))
      .catch((err) => console.log(`журнал: письмо на ${email} не ушло — ${err.code}, ${err.message}`));
    background.push(sending);
  }
  return { ok: true };
}

function forgotPasswordWithoutCatch(email) {
  if (registered.has(email)) void transport.sendMail(letter(email));
  return { ok: true };
}

for (const email of ['nobody@mail.ru', 'anya@mail.ru']) {
  console.log(`с catch, ${email} →`, forgotPassword(email));
}
await Promise.all(background);

console.log('без catch, anya@mail.ru →', forgotPasswordWithoutCatch('anya@mail.ru'));

релей 127.0.0.1:<порт>: соединение принимает, приветствия не шлёт
только connectionTimeout: 300 — через секунду письмо ещё в пути
с catch, nobody@mail.ru → { ok: true }
с catch, anya@mail.ru → { ok: true }
журнал: письмо на anya@mail.ru не ушло — ETIMEDOUT, Greeting never received
без catch, anya@mail.ru → { ok: true }
file://<пример>/node_modules/nodemailer/dist/esm/smtp-connection/index.js:779
            err = new Error(message);
                  ^

Error: Greeting never received
    at SMTPConnection._formatError (file://<пример>/node_modules/nodemailer/dist/esm/smtp-connection/index.js:779:19)
    at SMTPConnection._onError (file://<пример>/node_modules/nodemailer/dist/esm/smtp-connection/index.js:761:20)
    at Timeout.<anonymous> (file://<пример>/node_modules/nodemailer/dist/esm/smtp-connection/index.js:674:22)
    at <внутренние кадры node> {
  code: 'ETIMEDOUT',
  command: 'CONN'
}

Node.js v<версия>

Через секунду письмо всё ещё в пути, хотя таймаут соединения 300 мс. Сработать он и не мог: соединение установилось сразу, и таймер connectionTimeout в этот момент снимается. Дальше клиент ждёт приветствия, а на это свой таймаут — те самые 30 секунд по умолчанию. От релея, который молчит после соединения, защищает greetingTimeout, от замолчавшего посреди разговора — socketTimeout. Ставить нужно все три.

Обработчик с .catch ответил обоим адресам сразу и одинаково, а когда истёк greetingTimeout, в журнале появилась строка с кодом ETIMEDOUT и причиной Greeting never received. Обработчик без .catch тоже ответил сразу, клиент получил свой { ok: true } — а потом процесс упал с кодом 1. В браузере отклонённый промис без обработчика — строка в консоли, и программа идёт дальше («Необработанное отклонение»). В Node он завершает процесс вместе со всеми чужими запросами, которые тот обслуживал, и виноват в этом запрос, давно получивший ответ. Поэтому промис, которого никто не ждёт, всегда заканчивают .catch, даже если функция внутри свои ошибки ловит. Ловит она обычно не всё: у автора try в MailService обнимает только sendMail, а транспорт создаётся до него. Да и этот try может убрать следующая правка, а цена ошибки — весь процесс.

Чем же тогда письмо «обязано дойти»? Обязательство в почте есть, и у него точная граница. По RFC 5321 релей, ответивший 250 на письмо, переданное командой DATA, принимает ответственность за доставку или пересылку письма и не вправе потерять его по пустяковой причине, а если доставить потом не выйдет, обязан отправить уведомление о неудаче. До этого ответа письмо целиком на совести приложения, и у автора оно в таком случае теряется, оставив строку в журнале. Пользователь это переживёт: подождёт минуту и попросит снова. Письмо, которое терять нельзя вовсе, отправляют иначе: запись о нём сохраняют в базу, а отдельный работник шлёт и повторяет, пока релей не ответит 250. Это снова таблица — та самая, без которой автор решил обойтись.

Не ждать промис и не ловить его ошибку — разные решения. Первое бережёт ответ, второе роняет процесс.

Цену своего решения автор записал прямо рядом с ним:

// apps/api/src/auth/reset-token.ts, выдержка
/**
 * Ссылка восстановления — подписанный токен, а не строка в таблице.
 *
 * Отдельная таблица reset-токенов дала бы журнал выдач, но потребовала бы своей
 * миграции, чистки просроченных и транзакции на гашение. Стартеру это лишнее,
 * поэтому одноразовость обеспечивается иначе: секрет подписи выводится из
 * ТЕКУЩЕГО хеша пароля пользователя. Пароль сменился — хеш другой — все ранее
 * выданные ссылки перестают проверяться сами собой. Тем же свойством закрыт
 * и повторный переход по уже использованной ссылке.
 *
 * Что за это заплачено: в базе не остаётся следов запросов (аудита нет), пауза
 * между письмами держится в памяти процесса (см. AuthService), а выданные
 * подряд ссылки равнозначны — новая не гасит предыдущую, гаснут они разом при
 * первой же смене пароля. Нужен аудит, «живая только последняя ссылка» или
 * несколько инстансов API — заводите таблицу токенов.
 */
function resetSecret(baseSecret: string, passwordHash: string): string {
  return `${baseSecret}:password-reset:${passwordHash}`;
}

export function createResetToken(baseSecret: string, user: ResetSubject): string {
  return jwt.sign({ sub: user.id }, resetSecret(baseSecret, user.passwordHash), {
    expiresIn: RESET_TOKEN_TTL,
  });
}

Пройдём по пунктам. Выданные подряд ссылки равнозначны — это было видно в примере, где первая ссылка оставалась годной после выдачи второй. Таблица позволила бы правило «жива только последняя»: при выдаче новой ссылки прежние строки помечаются. Следов нет: когда просили ссылку, с какого адреса, по какой из них сменили пароль — по базе не восстановить, а это первое, что спросят при разборе угнанной учётки.

Пауза между письмами живёт в Map внутри сервиса. Перезапуск её обнуляет, а второй экземпляр API о ней не знает: на коде автора два экземпляра AuthService над одной базой отправили два письма в течение минуты там, где один экземпляр отправил бы одно. Пока экземпляр в compose один, это не беда; при масштабировании паузу придётся хранить там же, где всё общее для экземпляров.

Предпоследняя строка таблицы не про таблицу. Одноразовость у автора держится на том, что после перехода меняется хеш. Но чтение хеша, которым проверяется ссылка, и запись нового — два разных запроса к базе, а между ними считается bcrypt, около 80 мс. Два перехода по одной ссылке, пришедшие в этот промежуток, оба проверят её по старому хешу. На коде автора с базой-заглушкой оба одновременных сброса получили { ok: true }, а в базе остался только один из двух паролей — хотя письмо обещает, что ссылка «срабатывает один раз». Как закрыть эту щель одним условием в UPDATE, — в первой задаче.

И последнее, уже не о ссылке. Сброс пароля у автора меняет хеш и больше ничего. Токены входа подписаны общим секретом, от хеша не зависят и после сброса продолжают работать свои 30 дней: токен, выданный при регистрации, после смены пароля проходит verifyToken, а перепроверка в базе смотрит только, жив ли пользователь и та ли у него роль. Если пароль сбрасывают потому, что учётку угнали, угонщик со своим токеном остаётся внутри. OWASP советует после сброса спросить пользователя, завершить ли все его сеансы, или завершать их сразу. Проверка личности и так ходит в базу на каждом запросе (Проверка личности на каждом запросе), и для этого ей хватит времени последней смены пароля в строке пользователя: токен, выданный раньше, — отказ.

Отсутствие таблицы — не бесплатная простота, а список того, чего у системы нет. Хорошо, когда этот список записан рядом с кодом, как у автора.