@katomaran/nest-jwt-auth

@katomaran/nest-jwt-auth

This package provides utilities for creating, verifying, and decoding JSON Web Tokens (JWTs) with support for both access and refresh tokens. It is designed for NestJS applications that require JWT-based authentication.

Environment Variables This package relies on the following environment variables to be set in the parent application’s .env file:

REFRESH_TOKEN_KEY: Secret key for signing refresh tokens. ACCESS_PRIVATE_KEY: RSA private key for signing access tokens. ACCESS_PUBLIC_KEY: RSA public key for verifying access tokens. Example .env file:

env

REFRESH_TOKEN_KEY=your_refresh_token_secret
ACCESS_PRIVATE_KEY="your_private_key"
ACCESS_PUBLIC_KEY="your_public_key"

Installation

npm install @katomaran/nest-jwt-auth dotenv

Functions

createRefreshToken(_id: string): string Generates a refresh token signed with the REFRESH_TOKEN_KEY.

Parameters: _id (string) - The unique identifier of the user. Returns: A JWT refresh token as a string, valid for 30 days. Usage Example:

const refreshToken = jwtAuthService.createRefreshToken(user._id);
createAccessToken(payload: JwtPayload): string
Generates an access token using the ACCESS_PRIVATE_KEY, which is signed with the RS256 algorithm.

Parameters: payload (JwtPayload) - An object containing user data (_id, role, email). Returns: A JWT access token as a string, valid for 30 days. Usage Example:

const accessToken = jwtAuthService.createAccessToken({
  _id: user._id,
  role: user.role,
  email: user.email,
});
createVerificationAccessToken(payload: JwtPayload): string
Generates a verification access token with a shorter expiry, suitable for tasks like email verification.

Parameters: payload (JwtPayload) - An object containing user data (_id, role, email). Returns: A JWT verification token as a string, valid for 6 hours. Usage Example:

const verificationToken = jwtAuthService.createVerificationAccessToken({
  _id: user._id,
  role: user.role,
  email: user.email,
});
verifyAccessToken(token: string): JwtPayload | string
Verifies an access token using the ACCESS_PUBLIC_KEY. If the token is valid, it returns the payload; otherwise, it throws an error.

Parameters: token (string) - The JWT access token to be verified. Returns: The decoded payload if the token is valid; otherwise, an error is thrown. Usage Example:

try {
  const payload = jwtAuthService.verifyAccessToken(token);
  // Token is valid, proceed with payload data
} catch (error) {
  // Handle invalid token
}
verifyRefreshToken(token: string): JwtPayload | string
Verifies a refresh token using the REFRESH_TOKEN_KEY. If the token is valid, it returns the payload; otherwise, it throws an error.

Parameters: token (string) - The JWT refresh token to be verified. Returns: The decoded payload if the token is valid; otherwise, an error is thrown. Usage Example:

try {
  const payload = jwtAuthService.verifyRefreshToken(refreshToken);
  // Token is valid, proceed with payload data
} catch (error) {
  // Handle invalid token
}
verifyAdminToken(token: string): JwtPayload | string
Verifies an admin token using the ACCESS_PUBLIC_KEY, allowing secure access for admin-specific endpoints.

Parameters: token (string) - The JWT admin token to be verified. Returns: The decoded payload if the token is valid; otherwise, an error is thrown. Usage Example:

try {
  const payload = jwtAuthService.verifyAdminToken(adminToken);
  // Token is valid, proceed with payload data
} catch (error) {
  // Handle invalid token
}
decodeAdminToken(token: string): JwtPayload | null
Decodes an admin token without verifying its signature, useful for extracting information without validating authenticity.

Parameters: token (string) - The JWT admin token to decode. Returns: The decoded payload if the token is valid; null if decoding fails. Usage Example:

const decoded = jwtAuthService.decodeAdminToken(adminToken);
if (decoded) {
  // Proceed with decoded information
}
Example Usage in a NestJS Service
Here’s how you might use these functions in a NestJS authentication service:

import { Injectable } from '@nestjs/common';
import { JwtAuthService, JwtPayload } from '@katomaran/nest-jwt-auth';

@Injectable()
export class AuthService {
  constructor(private readonly jwtAuthService: JwtAuthService) {}

  async login(user: JwtPayload) {
    const accessToken = this.jwtAuthService.createAccessToken(user);
    const refreshToken = this.jwtAuthService.createRefreshToken(user._id);
    return { accessToken, refreshToken };
  }

  async validateAccessToken(token: string) {
    return this.jwtAuthService.verifyAccessToken(token);
  }
}

This setup provides all the tools needed to handle JWT-based authentication in a modular way, utilizing environment variables for security and flexibility.