@nasriya/authcrypto
v1.1.3
Published
AuthCrypto is a versatile cryptographic toolkit for handling JSON Web Tokens (JWT), password hashing, and secure token generation and verification. It provides robust methods for creating and managing JWTs, hashing and verifying passwords with secure algo
Downloads
61
Readme
AuthCrypto.
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.
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>'
})
:warning: Important Note
You must specify the
Crypto JWT_SECRET
variable in your environment, or set it usingauthCrypto.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 formatheader.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.