Guards determinan si una solicitud está permitida proceder al handler de la ruta — son el mecanismo dedicado de NestJS para autorización (y a menudo verificaciones de autenticación). Un guard devuelve true para permitir la solicitud o false/lanza una excepción para bloquearla.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Un guard implementa canActivate(), que devuelve un boolean (o Promise/Observable del mismo). Devolver false bloquea la solicitud con un 403; también puedes lanzar una excepción específica (p.ej. 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)
Los guards pueden aplicarse a nivel de método, controlador o global.
@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 un decorador @Roles() (metadatos) con un guard que lo lee (vía Reflector) es el patrón estándar para control de acceso basado en roles.
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.
Los guards son el mecanismo dedicado e idiomatic de NestJS para autorización — controlar qué solicitudes se permiten alcanzar handlers basado en autenticación y permisos.
Entenderlos es esencial porque prácticamente toda aplicación real necesita proteger rutas (requerir login, verificar roles/permisos), y los guards son la herramienta correcta para esto (mucho más limpio que meter lógica de autenticación en middleware o en cada handler).
Los patrones estándar — un guard JWT/autenticación que verifica credenciales y adjunta el usuario a la solicitud, y guards basados en roles que combinan un decorador @Roles() con un guard que lee Reflector para RBAC — son fundamentales para asegurar APIs NestJS.
El acceso de los guards al ExecutionContext rico (conocimiento del handler objetivo, clase y solicitud) es precisamente lo que los hace adecuados para decisiones de autorización que middleware no puede tomar limpiamente.
Saber cómo escribir, aplicar (método/controlador/global) y combinar guards con decoradores de metadatos es conocimiento fundamental para construir aplicaciones NestJS seguras y es un tema frecuente e importante arquitectónicamente en el framework.