📚 Summary

A clean and easy-to-use cryptography utility library for Node.js built on top of the native crypto module. It provides modern hashing, secure random generation, RSA key pair management, and digital signature utilities with a clean API.

Requirements

• Node.js v16+

🚀 Features

• 📌 Hash text values using SHA-1, SHA-256, SHA-512, and MD5
• 🔒 Compare hashed values securely using timingSafeEqual
• 🔑 Generate secure RSA 2048-bit key pairs
• ✍️ Create and verify digital signatures
• 🎲 Generate cryptographically secure random salts
• 📝 Fully typed with TypeScript

🔧 Usage

Install the library:

npm install @heliomarpm/cryptoh

✏️ Example Code

import cryptoh, { HashAlgorithm } from "cryptoh";

async function main() {
  // 👤 User registration (secure password storage)
  const password = "My$ecureP@ssword123";

  // Generate a unique salt for the user
  const salt = await cryptoh.random.generateSalt(16);

  // Concatenate password + salt and generate the hash
  const hashedPassword = await cryptoh.hash.generate(password + salt, HashAlgorithm.SHA512);

  console.log("Salt:", salt);
  console.log("Hashed password:", hashedPassword);

  // You would typically save this salt and hashedPassword to your database
  const storedCredentials = { salt, hashedPassword };

  // 👤 User login (password verification)
  const passwordAttempt = "My$ecureP@ssword123";

  // Recreate the hash with the stored salt and compare it to the stored hash
  const isPasswordValid = await cryptoh.hash.verify(
    passwordAttempt + storedCredentials.salt,
    storedCredentials.hashedPassword,
    HashAlgorithm.SHA512
  );

  console.log("Is password valid?", isPasswordValid); // true if matches

  // 🔐 Digital signature for sensitive payload (e.g., tokens, receipts, or important data)
  const payload = JSON.stringify({
    userId: 789,
    email: "[email protected]",
    timestamp: Date.now()
  });

  // Generate an RSA key pair
  const { publicKey, privateKey } = await cryptoh.keyPair.generate();

  // Sign the payload with the private key
  const signature = await cryptoh.sign.generate(payload, privateKey);

  console.log("Signature (base64):", Buffer.from(signature, "hex").toString("base64"));

  // Verify the signature using the public key
  const isSignatureValid = await cryptoh.sign.verify(payload, signature, publicKey);

  console.log("Is signature valid?", isSignatureValid); // true if signature matches
}

main();

📚 API Reference

See the API documentation for a complete list of available functions and their signatures.

🔒 cryptoh.hash

• Hashes the given text using the specified algorithm (default: SHA-256).
  generate(text: string, algorithm?: HashAlgorithm): Promise<string>

• Securely compares a plain text value with a given hash.
  verify(text: string, hash: string, algorithm?: HashAlgorithm): Promise<boolean>

🎲 cryptoh.random

• Generates a cryptographically secure random salt as a hex string. Default length: 16 bytes.
  generateSalt(length?: number): Promise<string>

🔑 cryptoh.keyPair

• Generates a 2048-bit RSA key pair with PEM encoding.
  generate(): Promise<{ publicKey: string, privateKey: string }>

✍️ cryptoh.sign

• Generates a digital signature for the provided data using the private key.
  generate(data: string, privateKey: string, algorithm?: HashAlgorithm): Promise<string>

• Verifies the authenticity of a digital signature.
  verify(data: string, signature: string, publicKey: string, algorithm?: HashAlgorithm): Promise<boolean>

📦 Project Scripts

• npm run check — runs formatter, linter and import sorting to the requested files
• npm run format — run the formatter on a set of files
• npm run lint — run various checks on a set of files
• npm run test — run unit tests
• npm run test:c — run unit tests with coverage
• npm run docs:dev — run documentation locally
• npm run commit - run conventional commits check
• npm run release:test — dry run semantic release
• npm run build — build library

📦 Dependencies

✅ Zero runtime dependencies — relies solely on Node.js native crypto module.
🔄 All devDependencies are pinned to latest stable versions

🤝 Contributing

We welcome contributions! Please read:

• Code of Conduct
• Contributing Guide

Thank you to everyone who has already contributed to the project!

Made with contrib.nn.

❤️ Support this project

If this project helped you in any way, there are several ways to contribute.
Help us maintain and improve this template:

⭐ Starring the repository
🐞 Reporting bugs
💡 Suggest features
🧾 Improving the documentation
📢 Share with others

💵 Supporting via GitHub Sponsors, Ko-fi, Paypal or Liberapay, you decide. 😉

📝 License

MIT © Heliomar P. Marques 🔝