@hatkom/aws-auth-guard

A NestJS module that integrates AWS Cognito JWT authentication into GraphQL applications. It validates Bearer tokens from incoming requests against a Cognito User Pool, resolves the authenticated user via a configurable lookup function, and applies a global guard that blocks unauthenticated access by default.

Features

• Global AuthGuard applied automatically to all GraphQL resolvers
• AWS Cognito JWT verification via aws-jwt-verify
• @Public() decorator to opt out of authentication on specific resolvers
• @GetUser() param decorator to inject the authenticated user into a resolver
• Generic user type — bring your own User model

Installation

npm install @hatkom/aws-auth-guard

Peer dependencies

npm install @nestjs/common @nestjs/core @nestjs/graphql aws-jwt-verify

Usage

1. Register the module

import { AuthModule } from '@hatkom/aws-auth-guard'
import { UserService } from './user/user.service'

@Module({
  imports: [
    AuthModule.forRootAsync<User, AppContext>({
      imports: [UserModule],
      inject: [UserService],
      useFactory: (userService: UserService) => ({
        credentials: {
          userPoolId: process.env.COGNITO_USER_POOL_ID,
          userPoolClientAppId: process.env.COGNITO_CLIENT_ID,
        },
        findUser: ({ cognitoId }) => userService.findByCognitoId(cognitoId),
      }),
    }),
  ],
})
export class AppModule {}

2. Use the decorators

import { GetUser, Public } from '@hatkom/aws-auth-guard'
import { Query, Resolver } from '@nestjs/graphql'

@Resolver()
export class ProfileResolver {
  // Protected by default — requires a valid Cognito token
  @Query(() => User)
  me(@GetUser() user: User) {
    return user
  }

  // Opt out of authentication for this resolver
  @Public()
  @Query(() => String)
  hello() {
    return 'world'
  }
}

3. Configure the GraphQL context

Pass the request object through the GraphQL context so the guard can access headers and attach the resolved user:

GraphQLModule.forRoot({
  context: ({ req }) => ({ req }),
})

API

AuthModule.forRootAsync(options)

| Option | Type | Description | | ------------ | --------------------------------------------------- | ---------------------------------------------------------------- | | useFactory | (...args) => AuthOptions \| Promise<AuthOptions> | Factory returning Cognito credentials and user lookup function | | inject | any[] | Providers to inject into the factory | | imports | any[] (optional) | Modules to import for the factory's dependencies |

AuthOptions<U>

| Field | Type | Description | | ---------------------------------- | ------------------------------------------------- | ------------------------------------------------------- | | credentials.userPoolId | string | AWS Cognito User Pool ID | | credentials.userPoolClientAppId | string | AWS Cognito App Client ID | | findUser | (params: { cognitoId: string }) => Promise<U \| null> | Resolves a user from the verified token's sub claim |

Decorators

| Decorator | Usage | Description | | ------------ | ------------------------------ | -------------------------------------------------------- | | @Public() | Method decorator on a resolver | Skips authentication for that resolver | | @GetUser() | Param decorator | Injects the authenticated user from the GraphQL context |

License

MIT