advanced-key-generator

advanced-key-generator is a library for generating random API (Application Programming Interface) keys or access tokens. By using this library, a Node.js backend service can generate API keys or access tokens, and then issue them to users and/or other services that require access to the capabilities and resources provided by the API service.

Table of contents

• Installation
• Usage
  • Generation Methods
• Options
  • string Method
  • bytes Method
  • base32 Method
  • base62 Method
  • uuidv4 Method
  • uuidv5 Method
  • sha256 Method
  • sha512 Method
  • jwt Method
  • md5 Method
• Security
• Change Log
• License

Installation

Using NPM:

$ npm install advanced-key-generator

Using Yarn:

$ yarn add advanced-key-generator

Usage

The advanced-key-generator library can generate API key/access tokens by utilizing several generation methods, such as string, bytes, base32, base62, uuidv4, uuidv5, sha256, sha512, jwt, and md5. Additionally, it provides functions to verify the validity of API keys and check if they have expired.

Importing:

// CommonJS Import
const { generateApiKey, verifyKey, isExpired } = require('advanced-key-generator');
// OR
const { default: generateApiKey, verifyKey, isExpired } = require('advanced-key-generator');

// ES6 Import
import { generateApiKey, verifyKey, isExpired } from 'advanced-key-generator';

Generation Methods

| Method | Description | | -------- | -----------------------------------------------------------------------| | string | Creates an API key/access token using random string generation | | bytes | Creates an API key/access token using random bytes | | base32 | Creates an API key/access token using a random UUID and converting itinto a Douglas Crockford Base32 encoded string | | base62 | Creates an API key using Base62 encoding | | uuidv4 | Creates an API key/access token using random UUID Version 4 generation | | uuidv5 | Creates an API key/access token using random UUID Version 5 generation | | sha256 | Creates an API key/access token using SHA-256 hash generation | | sha512 | Creates an API key/access token using SHA-512 hash generation | | jwt | Creates a JSON Web Token (JWT) using a specified payload and secret | | md5 | Creates an API key/access token using MD5 hash generation |

Options

See the Options section for detailed descriptions of available options for each generation method.

Example Usage

Generate an API Key

import { generateApiKey } from 'advanced-key-generator';

// Generate the API key using default method 'string'.
console.log(generateApiKey()); // ⇨ 'q_EaTiX+xbBXLyO05.+zDXjI+Qi_X0v'

// Generate an API key with expiration time.
const apiKey = generateApiKey({ method: 'string', length: 20, expiration: 3600 }); // 1 hour
console.log(`Generated API Key: ${apiKey}`);

Verify an API Key

import { verifyKey } from 'advanced-key-generator';

// Verify the generated API key.
const isValid = verifyKey(apiKey, 'string');
console.log(`Is API Key Valid? ${isValid}`);

Check if an API Key is Expired

You can check if an API key has expired using the isExpired function. Ensure that the object you pass to the function contains both the API key and its expiration timestamp (expiresAt).

Here's an example of how to use the isExpired function:

import { isExpired } from 'advanced-key-generator';

// Example API key with expiration timestamp
const apiKeyObject = {
  apiKey: 'your-api-key',
  expiresAt: 1724564930854 // Example expiration timestamp in milliseconds
};

// Check if the API key has expired
const expired = isExpired(apiKeyObject);
console.log(`Is API Key Expired? ${expired}`);

New Functions

verifyKey(apiKey, method)

Verifies if the provided API key matches the expected format for the given generation method.

| Parameter | Type | Description | | ---------- | ------ | ---------------------------------------------------------------- | | apiKey | string | The API key to verify | | method | string | The generation method used to create the key |

Returns true if the API key matches the expected format, otherwise false.

isExpired(apiKeyObject)

Check if the provided API key has expired based on its stored expiration date.

| Parameter | Type | Description | | ---------- | ------ | ---------------------------------------------------------------- | | apiKeyObject | object| An object containing the API key and its expiration date. The object should have the following properties: apiKey (string) and expiresAt (number). |

Returns true if the API key has expired, otherwise false.

Options

string Method

Creates an API key/access token using random string generation.

| Name | Default Value | Description | | ---------| ------------- | ----------------------------------------------------------------- | | method | string | To use the string generation method | | min | 16 | The minimum length of the API key (ignored if length is given) | | max | 32 | The maximum length of the API key (ignored if length is given) | | length | undefined | The length of the API key | | pool | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~+/ | The characters used for the API key generation | | prefix | undefined | A string prefix for the API key, followed by a period (.) |
| batch | undefined | The number of API keys to generate |

Examples:

import generateApiKey from 'advanced-key-generator';

// Generate the API key using default method 'string'.
console.log(generateApiKey()); // ⇨ 'q_EaTiX+xbBXLyO05.+zDXjI+Qi_X0v'

// Provide the generation method.
console.log(generateApiKey({ method: 'string' })); // ⇨ 'Zt1HbMcLKxk6~nnW'

// Create an API key with a certain length.
console.log(generateApiKey({ method: 'string', length: 8 })); // ⇨ 'TNJ6-Lo4'

// Create an API key with a length between a certain range.
console.log(generateApiKey({ method: 'string', min: 10, max: 20 })); // ⇨ 'ENwiOFdP8cWj'

// Create an API key with a certain pool of characters.
console.log(generateApiKey({
  method: 'string',
  pool: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
})); // ⇨ 'QFLSGIDLOUAELQZTQXMHQNJ'

// Create an API key with a prefix.
console.log(generateApiKey({ method: 'string', prefix: 'test_app' })); // ⇨ 'test_app.aTd34Rli0nir70/8'

// Create a batch (certain amount) of API keys.
console.log(generateApiKey({ method: 'string', batch: 5 })); 
// [
//   'w05KkI9AWhKxzvPFtXotUva-',
//   'YFL0ICl4PtLD8Y/oQ20iyAE',
//   'vJFbfeP_cpMYsH9l5BVHY23Ss',
//   '29~LIlSjDYFr5OrhU3f',
//   'UQc8Tp1d9elWAh7KDIMkjz2moFs'
// ]

jwt Method

Creates a JSON Web Token (JWT) using a specified payload and secret.

| Name | Default Value | Description | | ---------- | ------------- | ----------------------------------------------------------------- | | method | jwt | To use the jwt generation method | | payload | {} | The payload data to include in the JWT | | secret | undefined | The secret key used to sign the JWT | | expiresIn| undefined | Expiration time for the JWT | | algorithm| HS256 | The algorithm used to sign the JWT (e.g., HS256, RS256) | | prefix | undefined | A string prefix for the JWT, followed by a period (.) | | batch | undefined | The number of JWTs to generate |

Examples:

import generateApiKey from 'advanced-key-generator';

// Provide the generation method.
console.log(generateApiKey({ method: 'jwt', payload: { userId: 1 }, secret: 'mySecret' })); 
// ⇨ 'eyJ

hbGciOiAiSFMyNTYiLCAiaWF0IjoxNjE4MjU2OTU5LCAiZXhwIjoxNjE4MjcwNTU5fQ.eyJ1c2VySWQiOiAxfQ.qMc7aSVE_9xwbjLxnhecMxkXetZYq3Fphs4sdjQkMk'

md5 Method

Creates an API key/access token using MD5 hash generation.

| Name | Default Value | Description | | ---------- | ------------- | ----------------------------------------------------------------- | | method | md5 | To use the md5 generation method | | input | undefined | The input string to hash | | prefix | undefined | A string prefix for the API key, followed by a period (.) | | batch | undefined | The number of API keys to generate |

Examples:

import generateApiKey from 'advanced-key-generator';

// Generate the API key using MD5 hash generation.
console.log(generateApiKey({ method: 'md5', input: 'exampleString' })); 
// ⇨ '6c569aabb98f037b92c0e5f1d0f600d8'

Security

Ensure that you keep your API keys secure and do not expose them publicly. Use secure storage solutions such as environment variables or dedicated secrets management services to store and manage your keys.

Change Log

See the CHANGELOG.md file for details about the latest updates and changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

This README provides detailed examples for each method, ensuring that users can easily understand how to use each feature of the `advanced-key-generator` library. Make sure to replace placeholder links and

images with actual URLs relevant to your project. If you need more help or have other questions, feel free to ask!