JWT Module

This is a TypeScript library for working with JSON Web Tokens (JWT). It provides easy-to-use asynchronous methods to sign, extract, and verify JWTs using a variety of hashing algorithms.

Features

• Generate key pairs: Create keys for all supported algorithms.
• Sign JWTs: Create signed JWTs with custom payloads and options.
• Extract JWTs: Extract the header, payload, and signature from a JWT.
• Verify JWT Signature: Verify the signature of a JWT against a verify key.

Supported algorithms

This package supports all algorithms defined in RFC 7518 (JSON Web Algorithms (JWA)).

| Algorithm | Description | |-----------|-------------| | HS256 | HMAC using SHA-256 | | HS384 | HMAC using SHA-384 | | HS512 | HMAC using SHA-512 | | RS256 | RSASSA-PKCS1-v1_5 using SHA-256 | | RS384 | RSASSA-PKCS1-v1_5 using SHA-384 | | RS512 | RSASSA-PKCS1-v1_5 using SHA-512 | | ES256 | ECDSA using P-256 and SHA-256 | | ES384 | ECDSA using P-384 and SHA-384 | | ES512 | ECDSA using P-521 and SHA-512 | | PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256 | | PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384 | | PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512 |

Installation

You can install the module using npm or yarn:

npm install @payello-module/jwt
# or
yarn add @payello-module/jwt

Usage

Generating Key Pairs

To generate a key pair for a specific algorithm, you can use the generateKeys method:

import { JWT } from '@payello-module/jwt';

const alg = 'RS256'; // or any other supported algorithm

JWT.generateKeys(alg)
  .then(keyPair => {
    console.log('Sign Key (Private Key):', keyPair.sign.base64);
    console.log('Verify Key (Public Key):', keyPair.verify.base64);
  })
  .catch(error => console.error(error));

Signing a JWT

import { JWT } from '@payello-module/jwt';

const payload = { /* Your JWT payload here */ };
const alg = 'HS512'; // or any other supported algorithm
const key = 'your_signing_key';

JWT.sign(payload, alg, key)
  .then(token => console.log(token))
  .catch(error => console.error(error));

Extracting a JWT

import { JWT } from '@payello-module/jwt';

const token = 'your.jwt.token';

JWT.extract(token)
  .then(({ header, payload, signature }) => {
    console.log(header, payload, signature);
  })
  .catch(error => console.error(error));

Verifying a JWT

import { JWT } from '@payello-module/jwt';

const token = 'your.jwt.token';
const getVerifyKey = async (header, payload) => {
  // Logic to retrieve the verification key for the given header and payload
  return 'verify_key';
};

JWT.verifySignature(token, getVerifyKey)
  .then(({ verified, extracted }) => {
    if (verified) {
      console.log('JWT is verified');
      console.log(extracted);
    } else {
      console.log('JWT verification failed');
    }
  })
  .catch(error => console.error(error));

API Reference

JWT.generateKeys(alg?: JWTAlgorithm): Promise<JWTKeyPair>

Generates a new key pair for the given algorithm. If no algorithm is provided, it defaults to "HS256" (HMAC with SHA-256).

JWT.sign(payload: JWTPayload, alg: JWTAlgorithm, key: string | BufferSource): Promise<string>

Signs the provided payload and returns a JWT string.

JWT.extract(input: string, opts?: JwtExtractOpts): Promise<JwtExtract>

Extracts and returns the header, payload, and signature from a JWT string.

JWT.verifySignature(token: string, getVerifyKey: (header: JwtHeader, payload: JWTPayload) => Promise<BufferSource | string> | BufferSource | string, throwErrors?: boolean): Promise<{ verified: boolean, extracted: JwtExtract | null }>

Verifies a JWT string by checking the signature using the provided verification key. If throwErrors is set to true, it will throw a JwtError if the token is not valid.

Contributing

We welcome contributions to this module! Please consider the following guidelines when contributing:

1. Fork the repository and create your branch from main.
2. If you've added code that should be tested, add tests.
3. Ensure your code passes existing tests.
4. Ensure your code follows the existing code style.
5. Issue that pull request!