jwt: A TypeScript repository from andrewlubenets

A progressive Node.js framework for building efficient and scalable server-side applications.

Description

JWT utilities module for Nest based on the jsonwebtoken package.

Installation

$ npm i --save @nestjs/jwt

Usage

Import JwtModule:

@Module({
  imports: [JwtModule.register({ secret: 'hard!to-guess_secret' })],
  providers: [...],
})
export class AuthModule {}

Inject JwtService:

@Injectable()
export class AuthService {
  constructor(private readonly jwtService: JwtService) {}
}

Secret / Encryption Key options

If you want to control secret and key management dynamically you can use the secretOrKeyProvider function for that purpose.

JwtModule.register({
   /* Secret has precedance over keys */
  secret: 'hard!to-guess_secret',

  /* public key used in asymmetric algorithms (required if non other secrets present) */
  publicKey: '...',

  /* private key used in asymmetric algorithms (required if non other secrets present) */
  privateKey: '...'

  /* Dynamic key provider has precedance over static secret or pub/private keys */
  secretOrKeyProvider: (
    requestType: JwtSecretRequestType,
    tokenOrPayload: string | Object | Buffer,
    verifyOrSignOrOptions?: jwt.VerifyOptions | jwt.SignOptions
  ) => {
    switch (requestType) {
      case JwtSecretRequestType.SIGN:
        // retrieve signing key dynamically
        return 'privateKey';
      case JwtSecretRequestType.VERIFY:
        // retrieve public key for verification dynamically
        return 'publicKey';
      default:
        // retrieve secret dynamically
        return 'hard!to-guess_secret';
    }
  },
});

Async options

Quite often you might want to asynchronously pass your module options instead of passing them beforehand. In such case, use registerAsync() method, that provides a couple of various ways to deal with async data.

1. Use factory

JwtModule.registerAsync({
  useFactory: () => ({
    secret: 'hard!to-guess_secret'
  })
});

Obviously, our factory behaves like every other one (might be async and is able to inject dependencies through inject).

JwtModule.registerAsync({
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    secret: configService.getString('SECRET'),
  }),
  inject: [ConfigService],
}),

2. Use class

JwtModule.registerAsync({
  useClass: JwtConfigService
});

Above construction will instantiate JwtConfigService inside JwtModule and will leverage it to create options object.

class JwtConfigService implements JwtOptionsFactory {
  createJwtOptions(): JwtModuleOptions {
    return {
      secret: 'hard!to-guess_secret'
    };
  }
}

3. Use existing

JwtModule.registerAsync({
  imports: [ConfigModule],
  useExisting: ConfigService,
}),

It works the same as useClass with one critical difference - JwtModule will lookup imported modules to reuse already created ConfigService, instead of instantiating it on its own.

API Spec

The JwtService uses jsonwebtoken underneath.

jwtService.sign(payload: string | Object | Buffer, options?: SignOptions): string

The sign method is an implementation of jsonwebtoken .sign().

jwtService.signAsync(payload: string | Object | Buffer, options?: SignOptions): Promise<string>

The asynchronous .sign() method.

jwtService.verify<T extends object = any>(token: string, options?: VerifyOptions): T

The verify method is an implementation of jsonwebtoken .verify().

jwtService.verifyAsync<T extends object = any>(token: string, options?: VerifyOptions): Promise<T>

The asynchronous .verify() method.

jwtService.decode(token: string, options: DecodeOptions): object | string

The decode method is an implementation of jsonwebtoken .decode().

The JwtModule takes an options object:

secret is either a string, buffer, or object containing the secret for HMAC algorithms
secretOrKeyProvider function with the following signature (requestType, tokenOrPayload, options?) => jwt.Secret (allows generating either secrets or keys dynamically)
signOptions read more
privateKey PEM encoded private key for RSA and ECDSA with passphrase an object { key, passphrase } read more
publicKey PEM encoded public key for RSA and ECDSA
verifyOptions read more
secretOrPrivateKey (DEPRECATED!) read more

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

Author - Kamil Myśliwiec
Website - https://nestjs.com
Twitter - @nestframework

License

Nest is MIT licensed.

andrewlubenets/jwt