Guards determinam se uma requisição é permitida prosseguir para o handler da rota — são o mecanismo dedicado do NestJS para autorização (e frequentemente verificações de autenticação). Uma guard retorna true para permitir a requisição ou false/lança uma exceção para bloqueá-la.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Uma guard implementa canActivate(), que retorna um booleano (ou Promise/Observable de um). Retornar false bloqueia a requisição com um 403; você também pode lançar uma exceção específica (p.ex. UnauthorizedException).
@UseGuards(AuthGuard) // on a single route
@Get("profile")
getProfile() {}
@UseGuards(AuthGuard) // on a whole controller (all routes)
@Controller("admin")
export class AdminController {}
app.useGlobalGuards(new AuthGuard()); // globally (all routes)
Guards podem ser aplicadas no nível do método, controller ou globalmente.
@Injectable()
export class JwtAuthGuard implements CanActivate {
constructor(private jwtService: JwtService) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization?.split(" ")[1];
if (!token) throw new UnauthorizedException();
try {
request.user = await this.jwtService.verifyAsync(token); // attach the user
return true;
} catch {
throw new UnauthorizedException("Invalid token");
}
}
}
// a @Roles decorator stores required roles as metadata
@Roles("admin")
@Get("users")
listUsers() {}
// the RolesGuard reads the metadata and checks the user's roles
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(ctx: ExecutionContext): boolean {
const roles = this.reflector.get<string[]>("roles", ctx.getHandler());
const { user } = ctx.switchToHttp().getRequest();
return roles.some(role => user.roles?.includes(role)); // allow if the user has a required role
}
}
Combinar um decorador @Roles() (metadados) com uma guard que o lê (via Reflector) é o padrão padrão para controle de acesso baseado em papéis.
The ExecutionContext gives guards rich info (the handler, class, request) — more
than plain middleware — which is why guards (not middleware) are the right place
for authorization decisions.
Guards são o mecanismo dedicado e idiomático do NestJS para autorização — controlar quais requisições são permitidas alcançar handlers com base em autenticação e permissões.
Entender guards é essencial porque praticamente toda aplicação real precisa proteger rotas (exigir login, verificar papéis/permissões), e guards são a ferramenta correta para isso (muito mais limpo do que colocar lógica de autenticação em middleware ou em cada handler).
Os padrões padrão — uma guard de JWT/autenticação que verifica credenciais e anexa o usuário à requisição, e guards baseadas em papéis combinando um decorador @Roles() com uma guard que lê Reflector para RBAC — são fundamentais para proteger APIs NestJS.
O acesso das guards ao rico ExecutionContext (conhecendo o handler de destino, classe e requisição) é precisamente o que as torna adequadas para decisões de autorização que middleware não consegue fazer de forma limpa.
Saber como escrever, aplicar (método/controller/global) e combinar guards com decoradores de metadados é conhecimento fundamental para construir aplicações NestJS seguras e um tópico frequente e arquiteturalmente importante no framework.