@babl.one/jwt v0.1.4

babl.one Plugin :: JWT

This plugin provides functionality for working with JSON Web Tokens (JWT). It allows you to generate, sign, and verify JWTs using the HMAC-SHA512 algorithm with the blake2b512 hashing function. The plugin is designed to integrate with your application to handle user authentication and secure communication.

Overview

The JWT Plugin facilitates secure token-based authentication by creating, signing, and verifying JWTs. It includes functionality to handle JWT expiration, payloads, and security by checking the integrity of the token’s signature.

Features

• Generate JWT headers and payloads.
• Sign and validate JWTs using the blake2b512 algorithm.
• Set custom expiration times.
• Verify JWT integrity using a secret key.
• Support for expired tokens with custom expiration handling.

Installation

To use the JWT Plugin, you need to include it in your project and configure it properly. Follow these steps:

Step 1: Install the plugin

Ensure the plugin is included in your project via npm:

npm install @babl.one/jwt

Step 2: Configure and use the plugin in your application

In your app.ts (or similar entry point), import the plugin and initialize it:

import JWT from '@babl.one/jwt';

// Initialize JWT plugin
const jwt = new JWT();

// Example of signing a token with a secret
const token = jwt.sign('your-secret-key');

// Parse and validate the token
const parsedJWT = JWT.parse(token, 'your-secret-key');

Configuration

The plugin uses the JWTHeader interface to structure the JWT's header and payload. The JWT is signed using the blake2b512 hashing function. The token will automatically expire after a set time, which can be customized using the setExpires method.

API Documentation

Constructor

new JWT(parseJWT?: string, secret?: string, onExpiration?: (jwt: JWT) => JWT)

• parseJWT: Optional JWT string to parse.
• secret: Secret key to verify the JWT if parseJWT is provided.
• onExpiration: Optional callback to handle token expiration.

Methods

setPayload(payload: {})

Set the payload of the JWT. You can add any custom data to the token.

jwt.setPayload({ userId: 12345 });

setExpires(expiresInSec: number)

Set the expiration time of the JWT in seconds.

jwt.setExpires(3600); // Expires in 1 hour

sign(secret: string)

Sign the JWT using the provided secret key. This generates the JWT string.

const token = jwt.sign('your-secret-key');

static getPayload(jwt: string)

Retrieve the payload from the JWT string.

const payload = JWT.getPayload(token);

static parse(jwt: string, secret: string | "@PAYLOAD", onExpiration?: (jwt: JWT) => JWT)

Parse and verify the JWT. If the secret is provided, it will check the token's signature. If not, it will return the payload.

const parsedJWT = JWT.parse(token, 'your-secret-key');

Token Statuses

• VALID: The JWT is valid.
• EXPIRED: The JWT has expired.
• FAILED: The JWT is invalid due to incorrect signature or other issues.
• INSECURE: The JWT was parsed without a signature check.
• PENDING: The JWT is being created.
• CREATED: The JWT has been successfully created.

Example Usage

Create and Sign a JWT

import JWT from '@babl.one/jwt';

const jwt = new JWT();
jwt.setPayload({ userId: 12345 });
const token = jwt.sign('your-secret-key');
console.log(token);

Parse and Verify a JWT

import JWT from '@babl.one/jwt';

const parsedJWT = JWT.parse(token, 'your-secret-key');
if (parsedJWT.status === 'VALID') {
    console.log('JWT is valid!');
} else {
    console.log('Invalid or expired JWT');
}

Error Handling

• If the JWT is invalid or expired, the plugin will return the status FAILED or EXPIRED.
• If the signature doesn't match, the JWT will be marked as FAILED.

Conclusion

The JWT Plugin provides a simple and secure way to handle JWT authentication in your application. It integrates seamlessly with other plugins and is highly customizable for your token-based security needs.

For any questions or issues, please refer to the documentation or open an issue in the plugin repository.

Generated by the babl.one framework.