Stop writing boilerplate. Protect your routes with a decorator.
You're building a NestJS app. You chose AWS Cognito for authentication. Now you need to verify JWT tokens, handle multiple user pools, extract tokens from headers or cookies, and implement role-based authorization.
You could spend days writing boilerplate. Or you could use this.
One decorator protects your routes. Built on aws-jwt-verify.
@Controller('profile')
@Authentication() // That's it. Route protected.
export class ProfileController {
@Get()
getProfile(@CognitoUser() user: CognitoJwtPayload) {
return { username: user['cognito:username'] };
}
}- Fast setup — 5 minutes from install to protected routes
- Type-safe — Full TypeScript support
- Production-ready — Built on AWS's official JWT verification library
- Zero boilerplate — Decorators replace hundreds of lines
- Flexible — REST, GraphQL, cookies, multiple user pools, custom extractors
- Testable — Mock and E2E test utilities included
Install:
npm install @nestjs-cognito/core @nestjs-cognito/authConfigure:
import { CognitoAuthModule } from '@nestjs-cognito/auth';
@Module({
imports: [
CognitoAuthModule.register({
jwtVerifier: {
userPoolId: 'us-east-1_xxxxx',
clientId: 'your-client-id',
tokenUse: 'access',
},
}),
],
})
export class AppModule {}Protect routes:
import { Authentication, Authorization, CognitoUser } from '@nestjs-cognito/auth';
@Controller('admin')
@Authorization(['admin'])
export class AdminController {
@Get('dashboard')
getDashboard(@CognitoUser() user: CognitoJwtPayload) {
return { message: `Welcome ${user['cognito:username']}` };
}
}Done.
| Package | What it does | npm |
|---|---|---|
| @nestjs-cognito/core | JWT verification, token extraction | |
| @nestjs-cognito/auth | Decorators, guards, authorization | |
| @nestjs-cognito/graphql | GraphQL authentication | |
| @nestjs-cognito/testing | Mock and E2E test utilities |
@Controller('content')
export class ContentController {
@Get()
@Authorization({ allowedGroups: ['user', 'admin'] })
list() {
return { content: [] }; // Either user OR admin can access
}
@Post()
@Authorization({ requiredGroups: ['moderator', 'admin'] })
create() {
return { created: true }; // Must be BOTH moderator AND admin
}
@Delete(':id')
@Authorization({
allowedGroups: ['admin'],
prohibitedGroups: ['banned'] // Admins yes, banned users no
})
delete() {
return { deleted: true };
}
}@Controller('products')
@Authentication()
export class ProductsController {
@Get(':id')
@PublicRoute()
getProduct(@Param('id') id: string, @CognitoUser() user?: CognitoJwtPayload) {
const product = this.findProduct(id);
return {
...product,
price: user ? this.getMemberPrice(product) : product.regularPrice,
memberBenefits: user ? this.getBenefits(product) : null,
};
}
}import { GqlAuthentication, GqlAuthorization, GqlCognitoUser } from '@nestjs-cognito/graphql';
@Resolver()
@GqlAuthentication()
export class UserResolver {
@Query(() => User)
me(@GqlCognitoUser() user: CognitoJwtPayload) {
return {
id: user.sub,
username: user['cognito:username'],
email: user.email,
};
}
@Query(() => [User])
@GqlAuthorization(['admin'])
users() {
return this.userService.findAll();
}
}CognitoAuthModule.register({
jwtVerifier: [
{
userPoolId: 'us-east-1_customers',
clientId: 'customer-app-client',
tokenUse: 'access',
},
{
userPoolId: 'us-east-1_employees',
clientId: 'admin-app-client',
tokenUse: 'id',
},
],
})import { CookieJwtExtractor } from '@nestjs-cognito/core';
CognitoAuthModule.register({
jwtExtractor: new CookieJwtExtractor('access_token'),
jwtVerifier: {
userPoolId: 'us-east-1_xxxxx',
clientId: 'your-client-id',
tokenUse: 'id',
},
})import { CognitoTestingModule } from '@nestjs-cognito/testing';
const module = await Test.createTestingModule({
imports: [
CognitoTestingModule.register({}, {
enabled: true,
user: {
username: 'test-user',
email: '[email protected]',
groups: ['users'],
},
}),
AppModule,
],
})
.overrideProvider(COGNITO_JWT_VERIFIER_INSTANCE_TOKEN)
.useFactory({ factory: CognitoTestingModule.createJwtVerifierFactory })
.compile();Found a bug? Have an idea? Pull requests are welcome.
- Fork the repo
- Create your feature branch
- Commit your changes
- Push and open a PR
See CONTRIBUTING.md for details.
Package READMEs:
MIT
Made by @Lokicoule