README.md

Azion JWT Library

The Azion JWT Library provides utility functions for signing, verifying, and decoding JSON Web Tokens (JWTs). This library ensures ease of use and security when handling JWTs in web applications.

Table of Contents

• Installation
• Usage
  • Sign JWT
  • Verify JWT
  • Decode JWT
• API Reference
  • sign
  • verify
  • decode
• Types
  • JWTPayload
  • TokenHeader
• Errors
  • JwtAlgorithmNotImplemented
  • JwtTokenInvalid
  • JwtTokenNotBefore
  • JwtTokenExpired
  • JwtTokenIssuedAt
  • JwtHeaderInvalid
  • JwtTokenSignatureMismatched
• Contributing

Installation

Install the package using npm or yarn:

npm install azion

or

yarn add azion

Usage

Sign JWT

JavaScript:

import { sign } from 'azion/jwt';

const privateKey = 'your-private-key';
const payload = { userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }; // 1 hour expiration
sign(payload, privateKey).then((token) => console.log(token)); // Outputs the signed JWT

TypeScript:

import { sign } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const privateKey: string = 'your-private-key';
const payload: JWTPayload = { userId: 123, exp: Math.floor(Date.now() / 1000) + 3600 }; // 1 hour expiration
sign(payload, privateKey).then((token: string) => console.log(token)); // Outputs the signed JWT

Verify JWT

JavaScript:

import { verify } from 'azion/jwt';

const publicKey = 'your-public-key';
const token = 'your-jwt-token';
verify(token, publicKey)
  .then((payload) => console.log(payload))
  .catch((err) => console.error(err)); // Outputs the payload if verification is successful

TypeScript:

import { verify } from 'azion/jwt';
import type { JWTPayload } from 'azion/jwt';

const publicKey: string = 'your-public-key';
const token: string = 'your-jwt-token';
verify(token, publicKey)
  .then((payload: JWTPayload) => console.log(payload))
  .catch((err) => console.error(err)); // Outputs the payload if verification is successful

Decode JWT

JavaScript:

import { decode } from 'azion/jwt';

const token = 'your-jwt-token';
const { header, payload } = decode(token);
console.log(header, payload); // Outputs the decoded header and payload

TypeScript:

import { decode } from 'azion/jwt';
import type { JWTPayload, TokenHeader } from 'azion/jwt';

const token: string = 'your-jwt-token';
const { header, payload }: { header: TokenHeader; payload: JWTPayload } = decode(token);
console.log(header, payload); // Outputs the decoded header and payload

API Reference

sign

Signs a JWT payload with the specified algorithm and private key.

Parameters:

• payload: JWTPayload - The payload to be signed.
• privateKey: SignatureKey - The private key used for signing.
• alg?: SignatureAlgorithm - The algorithm to use for signing (default is 'HS256').

Returns:

• Promise<string> - The signed JWT.

verify

Verifies a JWT using the specified public key and algorithm.

Parameters:

• token: string - The JWT to verify.
• publicKey: SignatureKey - The public key used for verification.
• alg?: SignatureAlgorithm - The algorithm to use for verification (default is 'HS256').

Returns:

• Promise<JWTPayload> - The decoded payload if the token is valid.

decode

Decodes a JWT without verifying its signature.

Parameters:

• token: string - The JWT to decode.

Returns:

• { header: TokenHeader; payload: JWTPayload } - The decoded header and payload.

Types

JWTPayload

Defines the structure of the JWT payload.

type JWTPayload = {
  [key: string]: unknown;
  exp?: number;
  nbf?: number;
  iat?: number;
};

TokenHeader

Defines the structure of the JWT header.

interface TokenHeader {
  alg: SignatureAlgorithm;
  typ?: 'JWT';
}

Errors

JwtAlgorithmNotImplemented

Thrown when an algorithm is not implemented.

JwtTokenInvalid

Thrown when a JWT is invalid.

JwtTokenNotBefore

Thrown when a JWT is used before its nbf claim.

JwtTokenExpired

Thrown when a JWT has expired.

JwtTokenIssuedAt

Thrown when a JWT iat claim is in the future.

JwtHeaderInvalid

Thrown when a JWT header is invalid.

JwtTokenSignatureMismatched

Thrown when a JWT signature does not match.

Contributing

Feel free to submit issues or pull requests to improve the functionality or documentation.