argon2

An Argon2 library for Node

weekly downloads731K

versionv0.44.0

licenseMIT

categoryauth

argon2cryptoencryptionhashingpassword

Overview

The argon2 package provides Node.js bindings to the reference C implementation of Argon2, the winner of the Password Hashing Competition in 2015. It enables secure password hashing using a memory-hard algorithm specifically designed to resist brute-force attacks from GPUs, ASICs, and specialized hardware.

Argon2 addresses critical weaknesses in older algorithms like bcrypt and PBKDF2 by forcing attackers to use significant amounts of memory during each hash computation, making parallel attacks exponentially more expensive. The package supports three variants: Argon2d (maximizes resistance to GPU cracking), Argon2i (protects against side-channel attacks), and Argon2id (hybrid approach recommended by RFC 9106 and OWASP for general use).

With over 730,000 weekly downloads, argon2 has become the standard choice for authentication systems in modern Node.js applications. It provides a Promise-based API with configurable parameters for time cost, memory cost, and parallelism, allowing developers to tune security levels based on their specific threat model and hardware constraints. The library handles salting automatically and encodes hashes in a standard format that includes all parameters needed for verification.

The package requires native compilation but provides prebuilt binaries for common platforms including Linux (x86-64, ARM64), macOS, and Windows. It's maintained actively and follows security best practices, making it suitable for production environments handling user credentials, API keys, and other sensitive authentication data.

Quick Start

typescript

const argon2 = require('argon2');

class PasswordService {
  constructor() {
    this.options = {
      type: argon2.argon2id,
      memoryCost: 65536,
      timeCost: 3,
      parallelism: 4
    };
  }

  async hashPassword(plainPassword) {
    try {
      const hash = await argon2.hash(plainPassword, this.options);
      return hash;
    } catch (err) {
      throw new Error(`Hashing failed: ${err.message}`);
    }
  }

  async verifyPassword(hash, plainPassword) {
    try {
      const isValid = await argon2.verify(hash, plainPassword);
      
      if (isValid && await argon2.needsRehash(hash, this.options)) {
        return { isValid, needsRehash: true };
      }
      
      return { isValid, needsRehash: false };
    } catch (err) {
      return { isValid: false, needsRehash: false };
    }
  }
}

const passwordService = new PasswordService();

(async () => {
  const userPassword = 'MySecureP@ssw0rd!';
  
  const hash = await passwordService.hashPassword(userPassword);
  console.log('Hash:', hash);
  
  const result = await passwordService.verifyPassword(hash, userPassword);
  console.log('Valid:', result.isValid);
  console.log('Needs rehash:', result.needsRehash);
  
  const wrongResult = await passwordService.verifyPassword(hash, 'WrongPassword');
  console.log('Wrong password valid:', wrongResult.isValid);
})();

Use Cases

User Authentication Systems: Hash and verify user passwords during registration and login flows. The automatic salting and parameter embedding means you only need to store the hash string in your database, and verification extracts everything needed automatically.

API Key Generation: Create secure hashes for API keys and tokens that need to be verified repeatedly. The configurable time cost allows you to balance security with the performance requirements of high-traffic API endpoints.

Multi-Factor Authentication: Hash backup codes and recovery tokens with lower time/memory costs for faster verification while maintaining security through the memory-hard properties of Argon2.

Session Token Hashing: Generate and verify hashed session identifiers where you need cryptographic strength but can't use simple HMAC due to specific security requirements around memory-hardness.

Database Encryption Keys: Derive encryption keys from user passwords using Argon2's raw hash output mode, providing key stretching that makes dictionary attacks impractical even with leaked encrypted data.

Pros & Cons

Pros

+Memory-hard algorithm provides significantly better resistance to GPU and ASIC attacks compared to bcrypt or PBKDF2
+Highly configurable with independent control over time cost, memory cost, and parallelism for fine-tuned security/performance trade-offs
+Argon2id variant recommended by OWASP, RFC 9106, and security experts as the current best practice for password hashing
+Promise-based async API prevents blocking the event loop during computationally expensive hash operations
+Automatic salt generation and parameter embedding in hash output eliminates common implementation mistakes

Cons

−Requires native compilation which can complicate deployment in containerized environments or platforms without build tools
−Higher memory usage (typically 64MB+ per hash) can be problematic in memory-constrained environments or under DoS attacks
−Platform-specific prebuilt binaries may not cover all deployment targets, requiring manual compilation for ARM/Alpine Linux/exotic platforms
−Significantly slower than bcrypt at equivalent security levels, which may impact user experience during authentication
−Breaking API changes between major versions have historically required migration effort for production systems

Comparisons

bcryptjs vs argon2

auth

Install

bash

npm install argon2

bash

pnpm add argon2

bash

bun add argon2

Overview

Quick Start

typescript

const argon2 = require('argon2');

class PasswordService {
  constructor() {
    this.options = {
      type: argon2.argon2id,
      memoryCost: 65536,
      timeCost: 3,
      parallelism: 4
    };
  }

  async hashPassword(plainPassword) {
    try {
      const hash = await argon2.hash(plainPassword, this.options);
      return hash;
    } catch (err) {
      throw new Error(`Hashing failed: ${err.message}`);
    }
  }

  async verifyPassword(hash, plainPassword) {
    try {
      const isValid = await argon2.verify(hash, plainPassword);
      
      if (isValid && await argon2.needsRehash(hash, this.options)) {
        return { isValid, needsRehash: true };
      }
      
      return { isValid, needsRehash: false };
    } catch (err) {
      return { isValid: false, needsRehash: false };
    }
  }
}

const passwordService = new PasswordService();

(async () => {
  const userPassword = 'MySecureP@ssw0rd!';
  
  const hash = await passwordService.hashPassword(userPassword);
  console.log('Hash:', hash);
  
  const result = await passwordService.verifyPassword(hash, userPassword);
  console.log('Valid:', result.isValid);
  console.log('Needs rehash:', result.needsRehash);
  
  const wrongResult = await passwordService.verifyPassword(hash, 'WrongPassword');
  console.log('Wrong password valid:', wrongResult.isValid);
})();

Use Cases

Multi-Factor Authentication: Hash backup codes and recovery tokens with lower time/memory costs for faster verification while maintaining security through the memory-hard properties of Argon2.

Session Token Hashing: Generate and verify hashed session identifiers where you need cryptographic strength but can't use simple HMAC due to specific security requirements around memory-hardness.

Pros & Cons

Pros

+Memory-hard algorithm provides significantly better resistance to GPU and ASIC attacks compared to bcrypt or PBKDF2
+Highly configurable with independent control over time cost, memory cost, and parallelism for fine-tuned security/performance trade-offs
+Argon2id variant recommended by OWASP, RFC 9106, and security experts as the current best practice for password hashing
+Promise-based async API prevents blocking the event loop during computationally expensive hash operations
+Automatic salt generation and parameter embedding in hash output eliminates common implementation mistakes

Cons

−Requires native compilation which can complicate deployment in containerized environments or platforms without build tools
−Higher memory usage (typically 64MB+ per hash) can be problematic in memory-constrained environments or under DoS attacks
−Platform-specific prebuilt binaries may not cover all deployment targets, requiring manual compilation for ARM/Alpine Linux/exotic platforms
−Significantly slower than bcrypt at equivalent security levels, which may impact user experience during authentication
−Breaking API changes between major versions have historically required migration effort for production systems