Access Token Generator

A robust utility for generating JSON Web Tokens (JWTs) with support for tenant-based permissions, user payload customization, and flexible signing options. This package is ideal for applications requiring secure and scalable authentication and authorization mechanisms.

Features

Tenant-Based Permissions: Easily manage user roles and permissions across multiple tenants.
Customizable Payload: Define user-specific payload options, including metadata like account type, verification status, and more.
Flexible Signing Options: Supports symmetric and asymmetric algorithms for signing tokens.
Built-in Expiration Handling: Configure token expiration with absolute or relative time settings.
TypeScript Support: Fully typed interfaces for payloads, tenants, and configuration options.

Installation

npm install access-token-generator

yarn add access-token-generator

Usage

This library is designed to simplify the process of generating JWTs for authentication and authorization.

Basic Example

Create an access token for a user with default settings.

Code (src/example.ts):

import { AccessTokenGenerator } from 'access-token-generator';

const generator = new AccessTokenGenerator({
  payloadOptions: {
    email: '[email protected]',
    accountType: 'Admin',
    verified: true,
  },
  signingKey: 'your-secret-key',
});

const token = generator.getJWT(); // defaults to 15m expiry
console.log(token);

Tenant-Based Permissions

Generate a token with tenant-specific roles and permissions.

Code (src/example-tenants.ts):

import { AccessTokenGenerator } from 'access-token-generator';

const generator = new AccessTokenGenerator({
  payloadOptions: {
    email: '[email protected]',
    accountType: 'User',
    verified: true,
  },
  signingKey: 'your-secret-key',
  tenants: [
    { id: 'tenant1', role: 'Admin', permissions: ['read', 'write'] },
    { id: 'tenant2', role: 'Viewer', permissions: ['read'] },
  ],
});

const token = generator.getJWT(); // defaults to 15m expiry
console.log(token);

Advanced Configuration

Use an asymmetric signing algorithm and configure additional options.

Code (src/example-advanced.ts):

import { AccessTokenGenerator } from 'access-token-generator';
import { readFileSync } from 'fs';

const privateKey = readFileSync('./private-key.pem');

const generator = new AccessTokenGenerator({
  payloadOptions: {
    email: '[email protected]',
    accountType: 'User',
    verified: true,
  },
  signingKey: privateKey,
  algorithm: 'RS256',
  issuer: 'my-app',
});

const token = generator.getJWT({
  expiresAt: new Date(Date.now() + 3600 * 1000), // Set your own expiry
});
console.log(token);

Using `AccessTokenGenerator` in Tests

Here’s an example of how you might use the AccessTokenGenerator in a test suite. This demonstrates setting up a base tenant, adding/removing tenants, generating a new JWT for each test, and resetting the state before each test.

Test (__tests__/auth-token-generator.test.ts):

import { AccessTokenGenerator } from 'auth-token-generator';

describe('AccessTokenGenerator', () => {
  let generator: AccessTokenGenerator;

  beforeEach(() => {
    // Arrange: Set up the generator with a base tenant
    generator = new AccessTokenGenerator({
      payloadOptions: {
        email: '[email protected]',
        accountType: 'User',
        verified: true,
      },
      signingKey: 'test-secret-key',
      tenants: [
        { id: 'base-tenant', role: 'Admin', permissions: ['read', 'write'] },
      ],
    });

    // Reset the generator to its initial state before each test
    generator.reset();
  });

  it('should generate a JWT with the base tenant', () => {
    // Act: Generate a JWT
    const token = generator.getJWT({ expiredIn: '1h' });

    // Assert: Verify the token contains the base tenant
    const payload = JSON.parse(
      Buffer.from(token.split('.')[1], 'base64').toString()
    );
    expect(payload.tenants['base-tenant']).toEqual({
      r: 'Admin',
      p: ['read', 'write'],
    });
  });

  it('should add a new tenant and include it in the JWT', () => {
    // Act: Add a new tenant and generate a JWT
    generator.addTenant({
      id: 'new-tenant',
      role: 'Viewer',
      permissions: ['read'],
    });
    const token = generator.getJWT({ expiredIn: '1h' });

    // Assert: Verify the token contains the new tenant
    const payload = JSON.parse(
      Buffer.from(token.split('.')[1], 'base64').toString()
    );
    expect(payload.tenants['new-tenant']).toEqual({
      r: 'Viewer',
      p: ['read'],
    });
  });

  it('should remove a tenant and exclude it from the JWT', () => {
    // Act: Remove the base tenant and generate a JWT
    generator.removeTenant('base-tenant');
    const token = generator.getJWT({ expiredIn: '1h' });

    // Assert: Verify the token no longer contains the base tenant
    const payload = JSON.parse(
      Buffer.from(token.split('.')[1], 'base64').toString()
    );
    expect(payload.tenants['base-tenant']).toBeUndefined();
  });
});

Key Points:

beforeEach: Resets the generator to its initial state before each test using the .reset() method.
Adding/Removing Tenants: Use .addTenant() and .removeTenant() to modify the tenants dynamically.
JWT Generation: A new JWT is generated for each test using .getJWT().

This setup ensures that each test runs in isolation with a clean state.

API Reference