Skip to content

Latest commit

 

History

History
279 lines (220 loc) · 10.7 KB

README.md

File metadata and controls

279 lines (220 loc) · 10.7 KB
Raw

N|Solid

AuthCrypto.

Static Badge Repository Size Last Commit Status

Visit us at www.nasriya.net.

A powerful library for handling cryptographic operations and JWT.

Made with ❤️ in Palestine 🇵🇸

Overview

AuthCrypto is a powerful library for handling cryptographic operations and JWT (JSON Web Tokens) in Node.js applications. It provides utilities for hashing passwords, generating JWT tokens, and more.

Important

🌟 Support Our Open-Source Development! 🌟 We need your support to keep our projects going! If you find our work valuable, please consider contributing. Your support helps us continue to develop and maintain these tools.

Click here to support us!

Every contribution, big or small, makes a difference. Thank you for your generosity and support!

Features

  • Password Hashing: Securely hash and verify passwords with support for salts and multiple hashing algorithms.
  • JWT Management: Easily create and verify JSON Web Tokens for secure authentication.
  • Customizable Options: Configure hashing and JWT options to fit your application's needs.

Installation

You can install AuthCrypto via npm:

npm install @nasriya/authcrypto

Or using yarn:

yarn add @nasriya/authcrypto

Importing

Import in ESM module

import authCrypto from '@nasriya/authcrypto';

Import in CommonJS (CJS)

const authCrypto = require('@nasriya/authcrypto').default;

Configuration

AuthCrypto reads configuration values from environment variables or by setting them up manually:

A) Environment Variables

If you have full control over the source code, you can setup a .env file with the following properties:

AuthCrypto_ROUNDS=10
AuthCrypto_PASSWORDS_MIN=8
AuthCrypto_PASSWORDS_MAX=32
AuthCrypto_SECRET=Your_secret
  • AuthCrypto_ROUNDS: The number of hashing rounds for password hashing.
  • AuthCrypto_PASSWORDS_MIN: Minimum length for passwords (default: 8, min: 8).
  • AuthCrypto_PASSWORDS_MAX: Maximum length for passwords (default: 32).
  • AuthCrypto_SECRET*: A secret phrase to generate and verify JWT. Can be generated from crypto.generateSecret().

B) Manual Configuration

You can manually set some or all configurations using the config module as follows:

authCrypto.config.hashingRounds = 500;
authCrypto.config.minPasswordLength = 10;
authCrypto.config.maxPasswordLength = 32;
authCrypto.config.jwtSecret = '<a 64 bytes secret>';

Or you can configure them all like this:

authCrypto.config.set({
    hashingRounds: 500,
    minPasswordLength: 10,
    maxPasswordLength: 32,
    jwtSecret: '<a 64 bytes secret>'
})

⚠️ Important Note

You must specify the Crypto JWT_SECRET variable in your environment, or set it using authCrypto.config.jwtSecret, otherwise, your system might be at risk of forgery

Usage

Hashing

To hash strings, use the crypto API:

Hashing

const value = 'Something to hash';
authCrypto.crypto.hash(value);               // ⇨ b633c3e9f63478eb1fd0d311b1c35050644bf39d03e6f138a9ecf9ba2bc44cb77241dc5e08da50acb46053cafd11ac593a34d074d81c6b9b63a38e116ea14cba
authCrypto.crypto.hash(value, 'SHA512');     // ⇨ b633c3e9f63478eb1fd0d311b1c35050644bf39d03e6f138a9ecf9ba2bc44cb77241dc5e08da50acb46053cafd11ac593a34d074d81c6b9b63a38e116ea14cba
authCrypto.crypto.hash(value, 'SHA256');     // ⇨ ff75b3f89087a50f82c5fe8698d65a8ca8b2fdb9ddd698f8d0930b5ff963826d
authCrypto.crypto.hash(value, 'MD5');        // ⇨ b642e7e30f7eb096f02f02384163b1d8
authCrypto.crypto.hash(value, 'SHA1');       // ⇨ 2d7cb72b42172a3cb55b1db09fb4d96fcad14563

Generating Salt

// A 512-char salt
authCrypto.crypto.generateSalt();
// ⇨ a05c9ae0c36e82a09e4fb947c744701f498069816af016a0b6c233a3291cecaa3e1b12d7059a1eac93ea828aedb94de13347c50610e06514f495f9989f0182f1b2e283a4f95d61691784a77576f7e5f5318030707146a5547aca0ef9177eb996ef21f9be20c4f4a82ad8191d35c46a4d24f6c0460f7a025eb41c0ef6388f8fe79ea5b393c28b719734a842982bdd750e66ae84d74feea21b7ebfc8ba2a507011bffe54c2ebe7e09e529724ad49fc6623617f025a5acb8edc45348483471f5e5d97b7f7d93cc13aba90589be64b015faea678212ee61c40946c279c6436c5103cbe7805d09bd455005fbe08b4651c61f04d69d3299fcdcfc64b7f2293006b571d

// A 32-char salt
authCrypto.crypto.generateSalt(32);
// ⇨ a89cd25cc53ff2819e4916a54fffd474

Hashing + Salt

const value = 'Something to hash';
const salt = authCrypto.crypto.generateSalt(8);

authCrypto.crypto.saltHash(value, salt);               // ⇨ 120294cb8e1a5f03a6204b2aa86d2a6c4ad7484eb97d550dda7e9bef61ff7bf68f26f2155d057f477857aaff2a2da5d40e1492a314958185ab3f1cf064763fee
authCrypto.crypto.saltHash(value, salt, 'SHA512');     // ⇨ 120294cb8e1a5f03a6204b2aa86d2a6c4ad7484eb97d550dda7e9bef61ff7bf68f26f2155d057f477857aaff2a2da5d40e1492a314958185ab3f1cf064763fee
authCrypto.crypto.saltHash(value, salt, 'SHA256');     // ⇨ 5607d5a6eabd064c30f582966df3c303fcd81731efbc548014267d58426abc1f
authCrypto.crypto.saltHash(value, salt, 'MD5');        // ⇨ 7ad52f0862c310a186138681524eadc3
authCrypto.crypto.saltHash(value, salt, 'SHA1');       // ⇨ ea8971d4fc8bf334bed9d5799314c62fb7337eb7

Generating Secrets

You can generate 64 bytes (512 bit) secret keys using the crypto module.

authCrypto.crypto.generateSecret()
// ⇨ b7f8de80f54fb1e95597497fd19ff05319d02e6ebc4a0a762e291dbfa650ed05cdf226dfdbfa59a6059815333465c4303888cea666a1f75d9492a30773b2017c

Passwords

The Passwords module provides functionality for generating and verifying passwords with configurable options. Here's a detailed explanation of its features and how to use them.

1. Generating a Random Password

The generate method creates a random password based on the specified length and options.

Example Usage:

const password = authCrypto.passwords.generate(32, {
    includeNumbers: true,
    includeLetters: true,
    includeSymbols: true,
    beginWithLetter: true,
    noSimilarChars: true,
    noDuplicateChars: true,
    noSequentialChars: true
});

console.log(password);  // ⇨ ysYT"2U=Ekx|?}G!K{9#NIHP4d'fQ.b8

Explanation:

  • length: The length of the password, which must be between 8 and 32 characters.
  • options: An object to configure password generation:
    • includeNumbers: Whether to include numbers in the password.
    • includeLetters: Whether to include letters in the password.
    • includeSymbols: Whether to include symbols in the password.
    • beginWithLetter: If true, the password will start with a letter.
    • noSimilarChars: If true, avoids similar characters like 'i', 'l', '1', 'O'.
    • noDuplicateChars: If true, avoids duplicate characters in the password.
    • noSequentialChars: If true, avoids sequential characters.

2. Verifying a Password

The verify method checks if a provided password matches a previously hashed password.

Example Usage:

const plainPassword = 'mySecretPassword';
const hashedPassword = 'hashedPasswordFromDatabase'; // Assume this is a valid hashed password

const isMatch = Passwords.verify(plainPassword, hashedPassword);

console.log(isMatch); // ⇨ true if the password matches, otherwise false

Example with different algorith:

const options = {
    algorithm: 'SHA256' // Default: SHA512
}

const isMatch = Passwords.verify(plainPassword, hashedPassword, options);

console.log(isMatch); // ⇨ true if the password matches, otherwise false

Example Usage with salting:

const plainPassword = 'mySecretPassword';
const hashedPassword = 'hashedPasswordFromDatabase'; // Assume this is a valid hashed password
const options = {
    salt: 'optionalSalt', // If a salt was used during hashing
}

const isMatch = Passwords.verify(plainPassword, hashedPassword, options);

console.log(isMatch); // ⇨ true if the password matches, otherwise false

Explanation:

  • password: The plain text password to be verified.
  • hashedPassword: The previously hashed password to compare against.
  • salt: An optional salt that may have been used in the hashing process.

Validation:

  • Ensures that the minimum length is not greater than the maximum length.
  • Throws errors if the provided lengths are invalid or if they do not meet the required constraints.

Generating & Verifying JWT

The JWTManager module provides functionality for generating and verifying JSON Web Tokens (JWTs). It uses HMAC with the SHA-512 hash algorithm for signing tokens and offers robust methods for handling JWT operations.

1. Generating a JWT

The generate method creates a JWT token by encoding the header and payload, and then signing the token with a secret key.

Example Usage:

const token = authCrypto.jwt.generate({
    iss: 'auth.domain.com',
    exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24, // 24 hours from now or any time you want
    userid: 'a user id',
    sessionId: 'a session id',
    roles: ['user']
});

console.log(token); // Outputs the generated JWT token

Explanation:

  • payload: An object containing the claims you want to include in the JWT.
    • iat (issued at): Automatically set to the current time.
    • exp (expiration): Optional. If not provided, defaults to 24 hours from the current time.
    • iss (issuer): Optional. If not provided, defaults to 'auth.nasriya.net'.

Validation:

  • exp must be a number and should be at least 5 minutes in the future if provided.
  • iss must be a non-empty string if provided.

2. Verifying a JWT

The verify method checks the validity of a JWT token, including verifying its signature and expiration.

Example Usage:

const token = 'your.jwt.token'; // Replace with an actual JWT token

const result = authCrypto.jwt.verify(token);

if (result.valid) {
    console.log('Token is valid:', result.payload);
} else {
    throw new Error(result.message);
}

Explanation:

  • token: The JWT token to verify. It must be in the format header.payload.signature.
  • Returns: An object indicating the result of the verification:
    • valid: true if the token is valid, false otherwise.
    • payload: The decoded payload if the token is valid.
    • message: A description of why the token is invalid, if applicable.

License

Please read the license from here.