Стратегии Passport и JWT-аутентификация

Две стратегии, два момента

Аутентификация в Nest — это два разных момента, и Passport моделирует каждый отдельной стратегией. Первый момент — login: клиент шлёт логин и пароль ровно один раз, ты сверяешь их с базой, и если совпало — выдаёшь токен. Это LocalStrategy. Второй момент — каждый запрос после: клиент предъявляет токен, ты верифицируешь подпись и срок жизни и доверяешь личности внутри, не трогая базу. Это JwtStrategy. Стратегия — это класс, расширяющий PassportStrategy(...), чей метод validate() возвращает принципала, — и то, что вернёт validate(), Passport кладёт в req.user.

LocalStrategy читает учётные данные, сравнивает пароль с сохранённым хэшем и возвращает пользователя (без хэша). Парный LocalAuthGuard — это однострочник AuthGuard('local'), и его вешают на POST /login, чтобы стратегия отработала до хендлера:

import { Strategy } from 'passport-local';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import * as bcrypt from 'bcrypt';

@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private users: UsersService) {
    super(); // по умолчанию поля называются 'username' и 'password'
  }

  async validate(username: string, password: string) {
    const user = await this.users.findByName(username);
    if (!user || !(await bcrypt.compare(password, user.passwordHash))) {
      throw new UnauthorizedException();
    }
    const { passwordHash, ...safe } = user;
    return safe; // -> становится req.user
  }
}

Хендлер /login затем чеканит токен. К моменту запуска хендлера guard уже наполнил req.user, так что хендлеру остаётся лишь подписать payload — и никогда не клади в него пароль или что-либо секретное:

@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Request() req) {
  const payload = { sub: req.user.id, username: req.user.username };
  return { access_token: this.jwt.sign(payload) };
}

Проводка модуля: secret из конфига, а не из исходников

JwtModule нужны секрет для подписи и время жизни токена, и оба места — конфигурация, а не строковый литерал в репозитории. registerAsync позволяет внедрить ConfigService через useFactory, так что секрет приходит из окружения и ротируется без правки кода. PassportModule регистрирует инфраструктуру стратегий; свои классы-стратегии ты отдаёшь как обычные провайдеры:

@Module({
  imports: [
    PassportModule,
    JwtModule.registerAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        secret: config.getOrThrow<string>('JWT_SECRET'),
        signOptions: { expiresIn: '15m' }, // короткоживущий access-токен
      }),
    }),
  ],
  providers: [AuthService, LocalStrategy, JwtStrategy],
})
export class AuthModule {}

JwtStrategy — это верификатор. ExtractJwt.fromAuthHeaderAsBearerToken() велит Passport достать токен из Authorization: Bearer <token>; secretOrKey обязан быть тем же секретом, которым подписывали, иначе каждая верификация падает; а оставленный по умолчанию false у ignoreExpiration — это то, что и enforce-ит TTL. Passport верифицирует подпись и срок жизни до того, как запустится твой validate(), так что к моменту, когда ты видишь payload, он уже доказанно подлинный — тебе остаётся лишь сформировать принципала:

import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(config: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false, // отклонять просроченные токены (дефолт — оставь)
      secretOrKey: config.getOrThrow<string>('JWT_SECRET'),
    });
  }

  async validate(payload: { sub: string; username: string }) {
    return { userId: payload.sub, username: payload.username }; // -> req.user
  }
}

Fail closed: глобальный guard плюс @Public()

Опасный дефолт — защита по принципу opt-in: рассыпать @UseGuards(JwtAuthGuard) по каждому маршруту и надеяться, что никто ни один не забудет. Переверни это: зарегистрируй JWT-guard глобально через APP_GUARD, чтобы каждый маршрут был защищён по умолчанию, а затем вырежи явные дыры декоратором @Public(), который guard проверяет через Reflector. Забыть декоратор теперь означает оставить маршрут запертым, а не открытым — безопасный режим отказа.

// public.decorator.ts
export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// jwt-auth.guard.ts
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true; // @Public()-маршрут -> пропускаем JWT-верификацию
    return super.canActivate(context); // иначе запускаем AuthGuard('jwt')
  }
}

// app.module.ts — привязываем guard глобально
providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],

Теперь POST /login и GET /health несут @Public(); всё остальное требует валидный Bearer-токен. Поток от начала до конца:

Что лежит в req.user после каждого guard

Два guard’а наполняют req.user из разных источников, и путать их — частый баг. После LocalAuthGuard req.user — это то, что вернул LocalStrategy.validate(), то есть свежезагруженный пользователь из базы. После JwtAuthGuard req.user — это то, что вернул JwtStrategy.validate(payload), выведенное из claim’ов токена, а не из чтения базы. Если роли пользователя поменялись после выпуска токена, JWT-аутентифицированный запрос всё равно видит старые claim’ы, пока токен не истечёт.