RBAC: роли, guards и Reflector

RBAC: декоратор @Roles() плюс guard, который его читает

Если ты хоть раз видел тикет «пользователь удалил чужой контент», и оказалось, что на маршруте просто забыли guard, — ты понимаешь, почему авторизацию стоит выстраивать системно, а не латать после инцидента. Role-based access control (управление доступом на основе ролей) сопоставляет каждому пользователю набор ролей, а каждой роли — набор прав. В Nest идиоматичная кодировка — это метаданные: декоратор @Roles() штампует требуемые роли на хендлер или контроллер, а RolesGuard читает их назад через Reflector. Декоратор — меньшая половина: SetMetadata (или Reflector.createDecorator для типизированного ключа) — это всё, что нужно:

// roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
import { Role } from './role.enum'; // enum Role { Admin = 'admin', Editor = 'editor' }

export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

Guard — это место, где живёт решение. Он читает метаданные через getAllAndOverride, сравнивая сначала метаданные хендлера и откатываясь на контроллер, а затем проверяет роли аутентифицированного пользователя:

// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';
import { Role } from './role.enum';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
      context.getHandler(), // @Roles() на маршруте побеждает...
      context.getClass(),   // ...дефолт контроллера
    ]);
    if (!required) return true; // нет @Roles() на маршруте -> открыт
    const { user } = context.switchToHttp().getRequest();
    const ok = required.some((role) => user?.roles?.includes(role));
    if (!ok) throw new ForbiddenException(); // чистый 403 вместо голого false
    return ok;
  }
}

Две сеньорские детали. Первая: getAllAndOverride(key, [getHandler(), getClass()]) возвращает первое определённое значение в этом массиве — так что @Roles('admin') на уровне хендлера перекрывает дефолт уровня контроллера, и это ровно то старшинство, которое тебе нужно. (Его собрат getAllAndMerge вместо этого объединил бы их.) Вторая: возврат false даёт generic 403 без тела; выброс ForbiddenException позволяет отдать чистый 403 с сообщением — и твой exception filter отрисует его единообразно.

Композиция guards: сначала аутентификация, потом авторизация

RolesGuard читает user.roles. Этого поля не существует, пока не отработала аутентификация и не прикрепила req.user. Поэтому порядок — не косметика, а ограничение корректности: authn-guard (например, JwtAuthGuard) обязан выполниться до authz-guard, иначе RolesGuard прочитает undefined.roles и либо упадёт, либо откроется (fail open).

Когда ты привязываешь оба глобально через токен-провайдер APP_GUARD, Nest выполняет их в порядке объявления, так что перечисляй аутентификацию первой:

// app.module.ts
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    { provide: APP_GUARD, useClass: JwtAuthGuard }, // 1. устанавливает req.user
    { provide: APP_GUARD, useClass: RolesGuard },    // 2. читает user.roles
  ],
})
export class AppModule {}

Этот порядок также кодирует fail-closed дефолт: аутентифицируй глобально, и маршрут, который забыл добавить @Roles(), всё равно аутентифицирован — он просто открыт любому залогиненному пользователю, а не публике. Опасный обратный вариант — привязывать authz только по маршрутам: забудь привязку на одном хендлере, и у этого маршрута вообще нет гейта. Пропущенная привязка guard — это тихая дыра; предпочитай глобальную authn плюс явную authz.

Сеньорский предел: роли vs владение vs policy

Вот категориальная ошибка, которую прячет хук. RolesGuard выполняется во входной фазе, до хендлера, без загруженного доменного объекта. Он может оценить любой факт, уже лежащий на req.user, — роли, tenant id, scopes. Он не может оценить факт, который зависит от конкретной записи, потому что эта запись ещё не загружена. «Этот пользователь admin?» отвечается из одного req.user. «Владеет ли пользователь постом 4192?» требует SELECT ... WHERE id = 4192 и сравнения post.ownerId с user.id — запроса, который guard не должен делать, а одни параметры маршрута на это не ответят.

Поэтому resource/ownership-авторизация принадлежит туда, где загружен subject: в метод сервиса, который уже достал запись, или в policy guard, который загружает её намеренно. Втискивать владение в role guard — это не проблема тюнинга, которую чинят добавлением @Roles(): это означает задавать не тому слою вопрос, под который у него нет данных.

// владение живёт в сервисе, где запись уже в руках
async update(postId: number, dto: UpdatePostDto, user: AuthUser) {
  const post = await this.posts.findOneOrFail(postId);
  if (post.ownerId !== user.id && !user.roles.includes(Role.Admin)) {
    throw new ForbiddenException('not your post'); // владение, решённое ВМЕСТЕ с записью
  }
  return this.posts.save({ ...post, ...dto });
}

Когда роли начинают разрастаться — editor, senior-editor, editor-but-only-drafts, editor-of-section-X — это сигнал перейти от RBAC к policy-based / ABAC доступу. Вместо строк ты оцениваешь ability против subject. С CASL AbilityFactory строит правила на пользователя (включая record-shaped условия вроде { authorId: user.id }), а PoliciesGuard + @CheckPolicies() оценивает policy хендлера против этого ability:

// casl-ability.factory.ts — правила могут быть record-shaped
can(Action.Update, Article, { authorId: user.id }); // только свои статьи
can(Action.Read, 'all');

// policies.guard.ts — оценить policy маршрута против ability
@Injectable()
export class PoliciesGuard implements CanActivate {
  constructor(private reflector: Reflector, private abilityFactory: CaslAbilityFactory) {}

  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const handlers = this.reflector.get<PolicyHandler[]>(CHECK_POLICIES_KEY, ctx.getHandler()) ?? [];
    const { user } = ctx.switchToHttp().getRequest();
    const ability = this.abilityFactory.createForUser(user);
    return handlers.every((h) => (typeof h === 'function' ? h(ability) : h.handle(ability)));
  }
}

// controller — объявляем policy, а не сырую роль
@Patch(':id')
@CheckPolicies((a: AppAbility) => a.can(Action.Update, 'Article'))
update() {/* ... */}

Заметь честную оговорку: правило can(Action.Update, Article, { authorId: user.id }) обеспечивает владение лишь когда CASL передают реальный экземпляр Article для проверки. Проверка can(Action.Update, 'Article') против голого типа subject всё ещё не видит запись 4192 — ты либо сначала загружаешь статью и проверяешь экземпляр, либо проверка владения всё равно приземляется в сервис. ABAC поднимает выразительность выше; он не отменяет правило, что для суждения о владении нужна запись.

Какой слой владеет каким вопросом?

Правило: каждый вопрос авторизации, на который можно ответить из одного req.user и метаданных маршрута, принадлежит guard; каждый вопрос, который зависит от содержимого конкретной строки, обязан подождать, пока эта строка загружена, — а значит, слой сервиса или намеренно загружающий ресурс policy guard.