PasswordKit

A utility library for generating and validating strong passwords and one-time passwords (OTPs). Designed to help developers implement robust authentication mechanisms in their applications.

Why is PasswordKit Important?

In today’s digital age, weak passwords and insecure authentication practices are major causes of data breaches. PasswordKit addresses this challenge by providing tools for:

• Generating strong passwords based on customizable criteria.
• Validating password strength.
• Generating secure, expirable OTPs for two-factor authentication or verification processes.

Features

1. Password Generation:

   • Create strong, secure passwords with custom criteria (length, uppercase, numbers, special characters).

2. Password Validation:

   • Evaluate user-provided passwords against your security requirements.

3. OTP Generation and Validation:

   • Generate one-time passwords for use in login, account recovery, or verification processes.
   • Automatically manage OTP expiration with an in-memory caching system.

4. Customizable:

   • Define your own criteria for passwords and OTPs.

5. Lightweight and Isomorphic:

   • Works seamlessly in both Node.js and browser environments.

Installation

Install PasswordKit via npm:

npm install passwordkit

Usage

Password Generation

Generate a secure password by specifying custom criteria:

import { generatePassword } from "passwordkit";
const password = generatePassword({
  length: 12,
  includeUppercase: true,
  includeLowercase: true,
  includeNumbers: true,
  includeSpecialCharacters: true,
});

console.log(password);

/* 
    Example Output: "A1b2@C3d#E4f5"
*/

Parameters for generatePassword

| Parameter | Type | Description | | -------------------------- | ------- | ------------------------------------------------- | | length | number | Desired length of the password. | | includeUppercase | boolean | Include uppercase letters (A-Z). | | includeLowercase | boolean | Include lowercase letters (a-z). | | includeNumbers | boolean | Include numeric digits (0-9). | | includeSpecialCharacters | boolean | Include special characters (e.g., @, #, !, etc.). |

Password Validation

Evaluate the strength of a given password against predefined criteria:

import { checkPasswordStrength } from "passwordkit";
const result = checkPasswordStrength("P@ssword123", {
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSpecialCharacters: true,
});
console.log(result);

/* 
Output: 
    {   
      score: 5,
      messages: []
    } 
*/

Parameters for checkPasswordStrength

| Parameter | Type | Description | | -------------------------- | ------- | -------------------------------------------- | | password | string | The password to validate. | | minLength | number | Minimum length required for the password. | | requireUppercase | boolean | Require at least one uppercase letter (A-Z). | | requireLowercase | boolean | Require at least one lowercase letter (a-z). | | requireNumbers | boolean | Require at least one numeric digit (0-9). | | requireSpecialCharacters | boolean | Require at least one special character. |

Validation Result for checkPasswordStrength

| Key | Type | Description | | ---------- | -------- | ------------------------------------------------------ | | score | number | A score (0–5) based on how many criteria were met. | | messages | string[] | A list of reasons why the password is considered weak. |

OTP Generation and Validation

Generate an OTP

import { createOtp } from "passwordkit";
const otp = createOtp("user123", 300); // Generate OTP valid for 300 seconds (5 minutes)  console.log(`Your OTP is: ${otp}`);

/* 
    Example Output: "458201" 
*/

Parameters for createOtp

| Parameter | Type | Description | | ----------------- | ------ | -------------------------------------------------- | | key | string | A unique key to associate the OTP (e.g., user ID). | | expiryInSeconds | number | Expiry time for the OTP in seconds (default: 300). |

Validate an OTP

import { validateOtp } from "passwordkit";
const isValid = validateOtp("user123", "458201"); // Validate OTP  console.log(isValid ? "OTP is valid" : "OTP is invalid");

/* 
    Output:  OTP is valid 
*/

Parameters for validateOtp

| Parameter | Type | Description | | --------- | ------ | --------------------------------------- | | key | string | The unique key associated with the OTP. | | otp | string | The OTP to validate. |

OTP Lifecycle

1. Generate OTP:

   • Use createOtp to generate a time-limited OTP.
   • The OTP is stored in a lightweight in-memory cache.

2. Validate OTP:

   • Use validateOtp to check if the OTP is correct and still valid.
   • Once validated, the OTP is automatically removed from the cache.

3. Automatic Expiration:

   • OTPs expire after the defined time (default is 300 seconds) and are automatically removed from the cache.

Lifecycle of OTP

| Step | Description | | ------------ | --------------------------------------------------------------- | | Generate | Use createOtp to generate an OTP with a specific expiry time. | | Validate | Use validateOtp to check if the OTP is correct and valid. | | Expire | OTP automatically expires after the defined expiry time. |

Why Use Strong Passwords and OTPs?

Strong Passwords:

• Protect accounts from brute-force attacks.
• Ensure secure access to sensitive information.

OTPs:

• Add an extra layer of security through two-factor authentication (2FA).
• Verify user actions such as login, password recovery, or sensitive changes (e.g., updating email).

PasswordKit simplifies the implementation of these best practices, enabling developers to focus on building secure applications.

Example Use Case

Use Case 1: Secure Registration

• Step 1: Generate a random password for users who choose "generate password."
• Step 2: Validate user-provided passwords to meet security criteria.

Use Case 2: Two-Factor Authentication (2FA)

• Step 1: Generate an OTP when the user logs in or performs a sensitive action.
• Step 2: Validate the OTP within its expiry window to ensure secure verification.

Contributing

We welcome contributions! Please submit issues or pull requests via GitHub.

License

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