@alessiofrittoli/crypto-jwt v2.3.0

Crypto JSON Web Token 🔗

Lightweight TypeScript JSON Web Tokens library

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

Keep in mind that JSON Web Tokens can be easly decoded and they should never contains sensible informations!

JSON Web Tokens should be only used to store reference data (e.g. user ID). The token get then signed with the given "payload" and signature is verified to ensure the token hasn't been modified by third parties.

• Read more informations abot at RFC 7519 - Internet Engineering Task Force (IETF).

Table of Contents

• Getting started
• Supported Algorithms
• Jwt Class API Reference
  • Constructor
  • Properties
  • Methods
  • Example usage
  • Expiration
  • Not before
  • Type casting
• Error handling
• Development
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using crypto-jwt in your projects:

npm i @alessiofrittoli/crypto-jwt

or using pnpm

pnpm i @alessiofrittoli/crypto-jwt

Supported Algorithms

The Jwt class supports different algorithms. You will find detailed informations in this documentation on how to use them so you can choose the best fit for you needs.

If no algorithm is specified, HS256 is being used.

⚠️ Keep in mind that:

• you will need different key types based on the signing algorithm being used.
• usage of symmetric keys is insecure. Using asymmetric keys is recommended.

Jwt Class API Reference

Constructor

The Jwt class constructor accepts an object argument with the following properties:

Properties

Here are listed the Jwt class instance accessible properties:

Methods

The Jwt.sign() method synchronously generates and returns a new token string.

• It stores the result string in the Jwt.token property for further usage.
• The parsed header is being stored in the Jwt.header property.
• The iat property is being set to the current timestamp if none has been provided in the constructor.
• If the given data is an object, it's properties are being added to the Jwt.payload property.
• If the given data is not an object, it will be assigned to Jwt.payload.data property.
• stores the signature Buffer to the Jwt.signature property.

The Jwt.sign() method throws a new Exception when:

• no private key has been provided.
• no valid payload has been parsed.
• signature creation fails with the choosen algorithm due to invalid keys provided.

See Error Handling section for further informations.

The Jwt.verify() method synchronously verifies a token string and returns true on signature verification success.

It throws a new Exception when:

• no public key has been provided.
• no token value has been provided.
• wrong formatted token has been provided.
• the token is expired or not yet in charge.
• expected values mismatch in the token header/payload (Issuer, Audience, algorithm...).
• signature verification failures due to an invalid signature (altered token).
• signature verification failures due to an invalid public key.

See Error Handling section for further informations.

Example usage

Creating and verifying JSON Web Tokens

You can use the Jwt class to create or verify a JSON Web Token.

const jwt = new Jwt( {
  data    : 'Data encoded in the JWT payload.',
  header  : { alg: 'none' },
} )
console.log( jwt.sign() )

HS1/HS256/HS384/HS512

To create a JWT using HMAC secrets you need to specify a secret key in the key field of the Jwt constructor.

The private key could be any string, KeyObject or Binary data. It is suggested to use a 256 bit string.

HS1/HS256/HS384/HS512 (HMAC with SHA-1/SHA-256/SHA-384/SHA-512) is a symmetric keyed hashing algorithm that uses one secret key. Symmetric means two parties share the secret key. The key is used for both generating the signature and verifying it.

Be mindful when using a shared key; it can open potential vulnerabilities if the verifiers(multiple applications) are not appropriately secured.

Create the token

import crypto from 'crypto'
import { Jwt } from '@alessiofrittoli/crypto-jwt'

const secretKey = crypto.createSecretKey( Buffer.from( 'mysecretkey' ) )

const jwt = new Jwt( {
  data    : 'Data to be signed into the token.',
  key     : secretKey,
  header  : {
    alg: 'HS1', // HS1 | HS256 | HS384 | HS512
  },
} )
const signedJwt = jwt.sign()

Verify the token

const jwt = new Jwt( {
  token   : signedJwt,
  key     : secretKey,
  header  : {
    alg: 'HS1', // HS1 | HS256 | HS384 | HS512 -> expected algorithm.
  },
} )
const isValid = jwt.verify()

DS1/DS256/DS384/DS512

• Generate a keypair:

import crypto from 'crypto'

const keypair = crypto.generateKeyPairSync( 'dsa', {
  modulusLength       : 2048,
  divisorLength       : 256,
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

• Parse and sign a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const jwt = new Jwt( {
  data    : 'Data to be signed into the token.',
  key     : keypair.privateKey,
  header  : {
    alg: 'DS1', // DS1 | DS256 | DS384 | DS512
  },
} )
const signedJwt = jwt.sign()

• Parse and verify a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const jwt = new Jwt( {
  token   : signedJwt,
  key     : keypair.publicKey,
  header  : {
    alg: 'DS1', // DS1 | DS256 | DS384 | DS512 // expected algorithm
  },
} )
const isValid = jwt.verify()

ES256/ES384/ES512

Elliptic curve based JSON Web Signatures (JWS) provide integrity, authenticity and non-reputation to JSON Web Tokens (JWT).

The EC keys should be of sufficient length to match the required level of security. Note that while EC signatures are shorter than an RSA signature of equivalent strength, they may take more CPU time to verify.

EcDSA using P-256/384/521 and SHA-256/384/512

To generate a JWT signed with the ES256/ES384/ES512 algorithm and EcDSA keys you need to generate an asymmetric keys as follow:

• Generate a keypair:

import crypto from 'crypto'

const es256keypair = crypto.generateKeyPairSync( 'ec', {
  namedCurve          : 'secp256k1',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

const es384keypair = crypto.generateKeyPairSync( 'ec', {
  namedCurve          : 'secp384r1',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

const es512keypair = crypto.generateKeyPairSync( 'ec', {
  namedCurve          : 'secp521r1',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

• Parse and sign a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const es256Token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'ES256' },
  key     : es256keypair.privateKey,
} ).sign()

const es384Token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'ES384' },
  key     : es384keypair.privateKey,
} ).sign()

const es512Token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'ES512' },
  key     : es512keypair.privateKey,
} ).sign()

• Parse and verify a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const es256Valid = new Jwt( {
  token   : es256Token,
  header  : { alg: 'ES256' }, // expected algorithm
  key     : es256keypair.publicKey,
} ).verify()

const es384Valid = new Jwt( {
  token   : es384Token,
  header  : { alg: 'ES384' }, // expected algorithm
  key     : es384keypair.publicKey,
} ).verify()

const es512Valid = new Jwt( {
  token   : es512Token,
  header  : { alg: 'ES512' }, // expected algorithm
  key     : es512keypair.publicKey,
} ).verify()

• Generate a keypair:

import crypto from 'crypto'

const ed448keypair = crypto.generateKeyPairSync( 'ed448', {
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

const ed25519keypair = crypto.generateKeyPairSync( 'ed25519', {
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

• Parse and sign a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const ed448Token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'EdDSA' },
  key     : ed448keypair.privateKey,
} ).sign()

const ed25519Token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'EdDSA' },
  key     : ed25519keypair.privateKey,
} ).sign()

• Parse and verify a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const ed448Valid = new Jwt( {
  token   : ed448Token,
  header  : { alg: 'EdDSA' }, // expected algorithm
  key     : ed448keypair.publicKey,
} ).verify()

const ed25519Valid = new Jwt( {
  token   : ed25519Token,
  header  : { alg: 'EdDSA' }, // expected algorithm
  key     : ed25519keypair.publicKey,
} ).verify()

RS1/RS256/RS384/RS512

• Generate a keypair:

import crypto from 'crypto'

const bytes   = 256
const keypair = crypto.generateKeyPairSync( 'rsa', {
  modulusLength     : bytes * 8,
  publicKeyEncoding : { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
} )

• Parse and sign a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const signedJwt = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'RS1' }, // RS1 | RS256 | RS384 | RS512
  key     : keypair.privateKey,
} ).sign()

• Parse and verify a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const validToken = new Jwt( {
  token   : signedJwt,
  header  : { alg: 'RS1' }, // RS1 | RS256 | RS384 | RS512
  key     : keypair.publicKey,
} ).verify()

PS256/PS384/PS512

• Generate a keypair:

import crypto from 'crypto'

const bytes = 256

/** RSASSA-PSS using `SHA-256` and MGF1 with `SHA-256` */
const rsapss256keypair = crypto.generateKeyPairSync( 'rsa-pss', {
  modulusLength       : bytes * 8,
  hashAlgorithm       : 'SHA-256',
  mgf1HashAlgorithm   : 'SHA-256',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

/** RSASSA-PSS using `SHA-384` and MGF1 with `SHA-384` */
const rsapss384keypair = crypto.generateKeyPairSync( 'rsa-pss', {
  modulusLength       : bytes * 8,
  hashAlgorithm       : 'SHA-384',
  mgf1HashAlgorithm   : 'SHA-384',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

/** RSASSA-PSS using `SHA-512` and MGF1 with `SHA-512` */
const rsapss512keypair = crypto.generateKeyPairSync( 'rsa-pss', {
  modulusLength       : bytes * 8,
  hashAlgorithm       : 'SHA-512',
  mgf1HashAlgorithm   : 'SHA-512',
  publicKeyEncoding   : { type: 'spki', format: 'pem' },
  privateKeyEncoding  : { type: 'pkcs8', format: 'pem' },
} )

• Parse and sign a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const rsapss256token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'PS256' },
  key     : rsapss256keypair.privateKey,
} ).sign()

const rsapss384token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'PS384' },
  key     : rsapss384keypair.privateKey,
} ).sign()

const rsapss512token = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'PS512' },
  key     : rsapss512keypair.privateKey,
} ).sign()

• Parse and verify a token:

import { Jwt } from '@alessiofrittoli/crypto-jwt'

const rsapss256Valid = new Jwt( {
  token   : rsapss256token,
  header  : { alg: 'PS256' },
  key     : rsapss256keypair.publicKey,
} ).verify()

const rsapss384Valid = new Jwt( {
  token   : rsapss384token,
  header  : { alg: 'PS384' },
  key     : rsapss384keypair.publicKey,
} ).verify()

const rsapss512Valid = new Jwt( {
  token   : rsapss512token,
  header  : { alg: 'PS512' },
  key     : rsapss512keypair.publicKey,
} ).verify()

Using keys that requires a passphrase

Most of asymmetric key pairs allows you to set a passphrase for the Private Key. This passphrase must be provided in order to use that key for generating a signature.

Let's assume we got this keypair with the following passphrase:

import crypto from 'crypto'

const bytes       = 256
const passphrase  = 'my-private-key-optional-passphrase'
const keypair     = crypto.generateKeyPairSync( 'rsa', {
    modulusLength       : 256 * 8,
    publicKeyEncoding   : { type: 'spki', format: 'pem' },
    privateKeyEncoding  : { type: 'pkcs1', format: 'pem', passphrase, cipher: 'aes-256-cbc' },
} )

We can then sign a token as follow:

const jwt = new Jwt( {
  data    : 'Data to be signed into the token.',
  header  : { alg: 'RS1' },
  key     : {
    key         : keypair.privateKey,
    passphrase  : passphrase,
  },
} )

Expiration

By setting an expiration Date, the token will no longer be accepted on and after that Date. The Jwt.verify() method will then throw an Exception with the ErrorCode.EXPIRED code.

/** 5 minutes expiration token. */
const jwt = new Jwt( {
  exp: new Date().getTime() + ( 5 * 60 * 1000 ),
  ...
} )

Not before

By setting "not before" Date, the token will not be accepted on and before that Date. The Jwt.verify() method will then throw an Exception with the ErrorCode.TOO_EARLY code.

/** token should not be accepted in the next 5 minutes. */
const jwt = new Jwt( {
  nbf: new Date().getTime() + ( 5 * 60 * 1000 ),
  ...
} )

Type casting

By default the Jwt class will infer the type of the given data to the payload. So for example:

const jwt = new Jwt( {
  data: 'Data to be signed into the token.',
  ...
} )
// `jwt` -> `Jwt<string>`
// `jwt.payload.data` -> `string`

const jwt = new Jwt( {
  data: [ 1, 2, 3 ],
  ...
} )
// `jwt` -> `Jwt<number[]>`
// `jwt.payload.data` -> `number[]`

const jwt = new Jwt( {
  data: { property: 'value' },
  ...
} )
// `jwt` -> `Jwt<{property: string}>`
// `jwt.payload` -> `{property: string} & JsonWebToken.JwsPayload`

For obvious reasons the type cannot be inferred when "reading" a token and Jwt class will fallback to the type of unknown.

new Jwt( {
  token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoiQW4gdW5rbm93biB0eXBlIG9mIHBheWxvYWQiLCJpYXQiOjE3MzQzNzc3MTJ9.qptazZOXfAgFbMpVlPdGa6RstKlA945_-Qm1PhfmPIQ',
  ...
} ) // -> `Jwt<unknown>`

The Jwt class allows you to assing a custom type to the T parameter so that type can securely inferred to the payload data.

new Jwt<User>( {
  data: { id: 1 },
  ...
} ).payload // -> `User & JsonWebToken.JwsPayload`

const jwt = new Jwt<User>( {
  token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiaWF0IjoxNzM0Mzc4MDc0fQ.jt3-bjXe8NEyr9MEk5cvzCM_M_YcG9tpaWwKPhnIK8c',
  ...
} )
// `jwt.payload` // -> `User & JsonWebToken.JwsPayload`
// `jwt.payload.id` // -> safe type access

Error handling

This module throws a new Exception when an error occures providing an error code that will help in error handling.

The ErrorCode enumerator can be used to handle different errors with ease.

import { Exception } from '@alessiofrittoli/exception'
import { ErrorCode } from '@alessiofrittoli/crypto-jwt/error'

try {
  new Jwt( {
    token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.invalid'
  } ) // will throw error with code: ErrorCode.Jwt.WRONG_JWS
} catch ( error ) {
  if ( Exception.isException<string, ErrorCode>( error ) ) {
      switch ( error.code ) {
        case ErrorCode.Jwt.WRONG_JWS:
          // malformed JWT payload
          break
        // ... other cases here
        default:
          // unknown error
      }
  }
}

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕