RBAC: roles, guards and the Reflector

RBAC: a @Roles() decorator plus a guard that reads it

When you’ve seen authenticated routes quietly writable by any logged-in user — because someone forgot a guard — you understand why getting authorization right from the start matters more than patching it after the incident. Role-based access control maps each user to a set of roles, and each role to a set of permissions. In Nest the idiomatic encoding is metadata: a @Roles() decorator stamps the required roles onto a handler or controller, and a RolesGuard reads them back through the Reflector. The decorator is the smaller half — SetMetadata (or Reflector.createDecorator for a typed key) is all it takes:

// 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);

The guard is where the decision lives. It reads the metadata with getAllAndOverride, comparing the handler’s metadata first and falling back to the controller’s, then checks the authenticated user’s roles:

// 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(), // route-level @Roles() wins...
      context.getClass(),   // ...over the controller default
    ]);
    if (!required) return true; // no @Roles() on this route -> open
    const { user } = context.switchToHttp().getRequest();
    const ok = required.some((role) => user?.roles?.includes(role));
    if (!ok) throw new ForbiddenException(); // clean 403 instead of a bare false
    return ok;
  }
}

Two senior details. First, getAllAndOverride(key, [getHandler(), getClass()]) returns the first defined value in that array — so a handler-level @Roles('admin') overrides a controller-wide default, which is exactly the precedence you want. (Its sibling getAllAndMerge would union them instead.) Second, returning false yields a generic 403 with no body; throwing ForbiddenException lets you ship a clean, message-bearing 403 — and your exception filter renders it uniformly.

Guard composition: authentication first, authorization second

A RolesGuard reads user.roles. That field does not exist until authentication has run and attached req.user. So order is not cosmetic — it is a correctness constraint: the authn guard (e.g. a JwtAuthGuard) must execute before the authz guard, or RolesGuard reads undefined.roles and either crashes or fails open.

When you bind both globally with the APP_GUARD provider token, Nest runs them in declaration order, so list authentication first:

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

@Module({
  providers: [
    { provide: APP_GUARD, useClass: JwtAuthGuard }, // 1. establishes req.user
    { provide: APP_GUARD, useClass: RolesGuard },    // 2. reads user.roles
  ],
})
export class AppModule {}

This ordering also encodes a fail-closed default: authenticate globally, and a route that forgets to add @Roles() is still authenticated — it is merely open to any logged-in user, not open to the public. The dangerous inverse is binding authz per-route only: forget the binding on one handler and that route has no gate at all. A missing guard binding is a silent hole; prefer global authn plus explicit authz.

The senior limit: roles vs ownership vs policies

Here is the category error the hook hides. A RolesGuard runs in the inbound phase, before the handler, with no domain object loaded. It can evaluate any fact already on req.user — roles, tenant id, scopes. It cannot evaluate a fact that depends on a specific record, because that record has not been fetched yet. “Is this user an admin?” is answerable from req.user alone. “Does this user own post 4192?” requires SELECT ... WHERE id = 4192 and a comparison of post.ownerId to user.id — a query the guard has no business issuing and the route params alone cannot answer.

That is why resource/ownership authorization belongs where the subject is loaded: in the service method that already fetched the record, or in a policy guard that loads it deliberately. Pushing ownership into a role guard is not a tuning problem you can fix with more @Roles() — it is asking the wrong layer a question it has no data for.

// ownership lives in the service, where the record is already in hand
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'); // ownership, decided WITH the record
  }
  return this.posts.save({ ...post, ...dto });
}

When roles start to explode — editor, senior-editor, editor-but-only-drafts, editor-of-section-X — that is the signal to move from RBAC to policy-based / ABAC access. Instead of strings, you evaluate an ability against a subject. With CASL, an AbilityFactory builds per-user rules (including record-shaped conditions like { authorId: user.id }), and a PoliciesGuard + @CheckPolicies() evaluates a handler’s policy against that ability:

// casl-ability.factory.ts — rules can be record-shaped
can(Action.Update, Article, { authorId: user.id }); // own articles only
can(Action.Read, 'all');

// policies.guard.ts — evaluate the route's policy against the 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 — declare the policy, not a raw role
@Patch(':id')
@CheckPolicies((a: AppAbility) => a.can(Action.Update, 'Article'))
update() {/* ... */}

Note the honest caveat: a can(Action.Update, Article, { authorId: user.id }) rule only enforces ownership when CASL is handed a real Article instance to test. Checking can(Action.Update, 'Article') against the bare subject type still can’t see record 4192 — you either load the article first and test the instance, or the ownership check still lands in the service. ABAC moves the expressiveness up; it does not repeal the rule that you need the record to judge ownership.

Which layer owns which question?

The rule of thumb: every authorization question that can be answered from req.user and route metadata alone belongs in a guard; every question that depends on the contents of a specific row must wait until that row is loaded, which means the service layer or a deliberately resource-loading policy guard.