Refresh-токены, ротация и обнаружение повторного использования

Почему два токена: проблема отзыва

JWT access-токен самодостаточен: сервер проверяет его подпись и доверяет клеймам внутри без обращения к базе. Эта без-состоятельность и есть весь смысл — она масштабируется, и любой сервис с публичным ключом может его валидировать. Но у неё есть жёсткое следствие: ты не можешь отозвать JWT до его exp. Нет серверной записи, которую можно удалить; токен валиден до истечения, и точка. Так что если он утёк, твой единственный рычаг — насколько коротким ты сделал exp.

Это диктует дизайн. Держи access-токен коротким — ~15 минут — чтобы украденный был 15-минутной проблемой, а не вечной. Но нельзя заставлять пользователей логиниться каждые 15 минут, поэтому ты сочетаешь его с refresh-токеном — долгоживущим (~7–30 дней) — чья единственная работа в том, чтобы быть обменянным на /auth/refresh на новый access-токен.

import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';

@Injectable()
export class TokenService {
  constructor(private readonly jwt: JwtService) {}

  // two tokens, two secrets, two very different TTLs
  async issuePair(userId: string, familyId: string) {
    const accessToken = await this.jwt.signAsync(
      { sub: userId },
      { secret: process.env.ACCESS_SECRET, expiresIn: '15m' },   // short: caps theft blast radius
    );
    const refreshToken = await this.jwt.signAsync(
      { sub: userId, familyId },
      { secret: process.env.REFRESH_SECRET, expiresIn: '30d' },  // long: avoids constant re-login
    );
    return { accessToken, refreshToken };
  }
}

Refresh-токен теперь — чувствительная учётка: он живёт неделями и чеканит access-токены по требованию. Поэтому он обязан быть серверно-отслеживаемым (в отличие от без-состоятельного access-токена) и никогда не должен касаться доступного из JS хранилища. Он путешествует как httpOnly, Secure, SameSite cookie: httpOnly держит его вне document.cookie, чтобы XSS не мог его прочитать, Secure прикрепляет его к HTTPS, SameSite притупляет CSRF. Access-токен может лежать в памяти; refresh-токен сидит в закалённой cookie.

Ротация: сделай каждый refresh одноразовым

Наивный дизайн возвращает тот же refresh-токен на всю его 30-дневную жизнь. Это ровно та отмычка из инцидента: одна утечка покупает 30 дней тихого доступа. Ротация чинит проблему времени жизни: при каждом вызове /auth/refresh ты выпускаешь совершенно новый refresh-токен и инвалидируешь старый. Каждый refresh-токен одноразовый.

async refresh(presentedToken: string) {
  const record = await this.findFamilyRecord(presentedToken); // looks up by hash (below)
  if (!record || record.revoked) throw new UnauthorizedException();

  // ROTATION: the old token is now spent; mint a fresh pair on the same family
  await this.markConsumed(record.id);
  return this.issuePair(record.userId, record.familyId);
}

Ротация делает две вещи. Она сжимает окно валидности — утёкший refresh-токен годен только до следующего refresh легитимного клиента, часто минуты, а не недели. И, что критично, она даёт тебе сигнал обнаружения: раз токен ротирован, предъявление его снова аномально, а на аномалии ты можешь реагировать.

Обнаружение повторного использования: израсходованный токен — это растяжка

Вот основной механизм. Ротированный refresh-токен одноразовый, так что его никогда не должны увидеть снова. Если израсходованный refresh-токен всё же предъявлен второй раз, есть только одно объяснение: им владеют двое — легитимный клиент и вор. Утечка уже случилась; повторное предъявление — это система, говорящая тебе об этом.

Сложность в том, что ты не можешь сказать, кто из них кто. Запрос от атакующего и запрос от жертвы выглядят одинаково — оба несут когда-то валидный токен. Так что ты делаешь единственное безопасное допущение: компрометация. Ты отзываешь всю семью токенов — каждый refresh-токен, происходящий от исходного логина, — что заставляет полную переаутентификацию.

Моделируй это как семью. Каждый логин начинает семью (familyId); каждая ротация прицепляет следующий токен к той же семье. Запись семьи отслеживает, какой токен сейчас жив и отозвана ли семья.

// При refresh: если предъявленный токен УЖЕ был использован — это повторное использование → убить семью
async refresh(presentedToken: string) {
  const record = await this.findByHash(this.hash(presentedToken));
  if (!record) throw new UnauthorizedException();

  if (record.consumed) {
    // REUSE DETECTED: a single-use token came back. Two holders exist.
    await this.revokeFamily(record.familyId);  // nuke every descendant of this login
    throw new UnauthorizedException('token reuse detected');
  }

  await this.markConsumed(record.id);
  const familyId = record.familyId;
  return this.issuePairAndStore(record.userId, familyId);
}

Теперь переиграй инцидент с ротацией на месте. Атакующий крадёт refresh-токен и использует его, чтобы отчеканить access-токен — ладно, он ротировал его, теперь держит токен v2. Позже настоящий пользователь, его клиент, делает refresh с токеном, который он всё ещё держит (тот, что атакующий уже израсходовал, v1). Сервер видит израсходованный токен, предъявленный снова → повтор обнаружен → он отзывает всю семью. И v2 атакующего, и любой будущий refresh умирают. Пользователя выбрасывает на экран логина, он переаутентифицируется и начинает свежую семью; атакующий заблокирован. Окно в 26 дней схлопывается до «до следующего refresh пользователя».

Хранение: хешируй refresh-токен, никогда не храни сырым

Запись семьи живёт в твоей базе — но ты не должен хранить в ней сырой refresh-токен. Если бы хранил, утечка базы (дамп, бэкап, оставленный в бакете, read-only SQLi) вручила бы атакующему каждый живой refresh-токен в открытом виде: мгновенный угон аккаунтов в масштабе, без подделки подписи. Вместо этого храни только хеш refresh-токена — argon2/bcrypt или простой SHA-256, раз токен уже высокоэнтропийный — ровно как хранил бы пароль. При refresh хешируй предъявленный токен и сравнивай с сохранённым значением.

import { createHash } from 'node:crypto';

// the token is high-entropy random already, so a fast SHA-256 is fine here
private hash(token: string): string {
  return createHash('sha256').update(token).digest('hex');
}

private async issuePairAndStore(userId: string, familyId: string) {
  const { accessToken, refreshToken } = await this.tokens.issuePair(userId, familyId);
  await this.familyRepo.save({
    familyId,
    userId,
    tokenHash: this.hash(refreshToken), // store the HASH, never the raw token
    consumed: false,
    revoked: false,
  });
  return { accessToken, refreshToken };
}

Обвязка в Nest зеркалит access-путь, но остаётся отдельной: JwtRefreshStrategy (отдельная от access-овой JwtStrategy) читает refresh-токен из cookie и валидирует его подпись refresh-секретом; эндпоинт /auth/refresh ограждён ею; а сервис делает stateful-часть — ищет семью по хешу, проверяет consumed/revoked, ротирует, сохраняет новый хеш, возвращает новую пару. @nestjs/jwt подписывает оба токена, но разными секретами и разными TTL, так что access-токен никогда не может быть переигран как refresh-токен и наоборот.