@hicaru/argon2-pure.js v0.0.4

@hicaru/argon2-pure.js

A pure TypeScript/JavaScript implementation of the Argon2 password hashing algorithm. This implementation provides full support for Argon2d, Argon2i, and Argon2id variants with no native code dependencies.

Features

• 100% pure TypeScript/JavaScript implementation, no native code dependencies
• Works in all JavaScript environments (browser, Node.js, etc.)
• Full support for all Argon2 variants:
  • Argon2d (data-dependent hashing, faster but potentially vulnerable to side-channel attacks)
  • Argon2i (data-independent hashing, resistant to side-channel attacks)
  • Argon2id (hybrid mode, combines security benefits of both)
• Support for both Argon2 versions:
  • Version 1.0 (0x10)
  • Version 1.3 (0x13, the latest version)
• Complies with the RFC 9106 specification

Installation

npm install @hicaru/argon2-pure.js

Usage

Basic Usage

import { 
  hashEncoded, 
  verifyEncoded, 
  Config, 
  Variant 
} from '@hicaru/argon2-pure.js';

// Create a hash with default parameters (Argon2id)
const password = new TextEncoder().encode("mySecurePassword");
const salt = new TextEncoder().encode("somesalt");  // In practice, generate a random salt
const hash = hashEncoded(password, salt, new Config());

console.log(hash);
// $argon2id$v=19$m=19456,t=2,p=1$c29tZXNhbHQ$...

// Verify a password against a hash
const isValid = verifyEncoded(hash, password);
console.log(isValid); // true

Advanced Usage

import { 
  hashRaw, 
  hashEncoded, 
  verifyEncoded, 
  Config, 
  Variant, 
  Version 
} from '@hicaru/argon2-pure.js';

// Configure custom parameters
const config = new Config(
  new Uint8Array(),  // Additional data (optional)
  32,                // Hash length in bytes
  4,                 // Parallelism (lanes)
  4096,              // Memory cost (KB)
  new Uint8Array(),  // Secret key (optional)
  3,                 // Time cost (iterations)
  Variant.Argon2i,   // Algorithm variant
  Version.Version13  // Version 1.3
);

const password = new TextEncoder().encode("password");
const salt = new TextEncoder().encode("somesalt");

// Get raw hash bytes
const rawHash = hashRaw(password, salt, config);

// Get encoded hash string
const encodedHash = hashEncoded(password, salt, config);
console.log(encodedHash);
// $argon2i$v=19$m=4096,t=3,p=4$c29tZXNhbHQ$...

// Verify password against encoded hash
const isValid = verifyEncoded(encodedHash, password);
console.log(isValid); // true

Predefined Configurations

The library provides several predefined configurations:

import { Config } from '@hicaru/argon2-pure.js';

// Original Argon2 paper configuration
const originalConfig = Config.original();

// OWASP recommended configurations
const owasp1Config = Config.owasp1();
const owasp2Config = Config.owasp2();

// RFC 9106 recommended configuration
const rfcConfig = Config.rfc9106();
const rfcLowMemConfig = Config.rfc9106LowMem();

Configuration Options

The Config class accepts these parameters:

Predefined Configurations

API Reference

Core Functions

hashRaw(pwd: Uint8Array, salt: Uint8Array, config: Config): Uint8Array

Generates a raw hash output for the given password, salt, and configuration.

hashEncoded(pwd: Uint8Array, salt: Uint8Array, config: Config): string

Generates an encoded hash string (PHC format) for the given password, salt, and configuration.

verifyEncoded(encoded: string, pwd: Uint8Array): boolean

Verifies if the password matches the encoded hash.

verifyEncodedExt(encoded: string, pwd: Uint8Array, secret: Uint8Array, ad: Uint8Array): boolean

Verifies if the password matches the encoded hash, with additional secret key and associated data.

verifyRaw(pwd: Uint8Array, salt: Uint8Array, hash: Uint8Array, config: Config): boolean

Verifies if the password matches the raw hash with the provided configuration.

encodedLen(variant: Variant, memCost: number, timeCost: number, parallelism: number, saltLen: number, hashLen: number): number

Calculates the length of the encoded hash string.

Enums

Variant

• Variant.Argon2d: Data-dependent hashing (faster but potentially vulnerable to side-channel attacks)
• Variant.Argon2i: Data-independent hashing (resistant to side-channel attacks)
• Variant.Argon2id: Hybrid mode, combines Argon2d and Argon2i

Version

• Version.Version10: Argon2 version 1.0 (0x10)
• Version.Version13: Argon2 version 1.3 (0x13)

Classes

Config

Configuration class for Argon2 parameters.

Static Methods

• Config.original(): Returns original Argon2 paper configuration (Argon2i, 4096 KB, t=3)
• Config.owasp1(): Returns OWASP recommended configuration for high security
• Config.owasp2(): Returns OWASP recommended configuration for moderate security (default)
• Config.owasp3(), Config.owasp4(), Config.owasp5(): Alternative OWASP configurations
• Config.rfc9106(): Returns RFC 9106 standard recommendation (2 GB memory)
• Config.rfc9106LowMem(): Returns RFC 9106 low-memory recommendation (64 MB memory)

Implementation Details

This library implements the Argon2 algorithm as specified in RFC 9106:

• Uses Blake2b for the initial hashing phase
• Implements the memory-hard function with data-dependent (Argon2d) or data-independent (Argon2i) addressing
• Provides the hybrid mode (Argon2id) that combines both approaches
• Supports parallelism through multiple lanes
• Implements variable-length output hashing

Limitations

• Performance is slower compared to native implementations due to the JavaScript runtime
• For high-security production environments with heavy usage, consider using native implementations like node-argon2
• The library is primarily designed for environments where native code is not available or deployable

Security Recommendations

For production use:

1. Always generate cryptographically secure random salts for each hash (at least 16 bytes)
2. Choose appropriate memory and time parameters based on your security requirements and hardware constraints
3. For most web applications, use Argon2id variant (the default)
4. Follow OWASP or RFC 9106 recommendations for memory and time parameters

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

References

• Argon2 GitHub Repository
• RFC 9106: Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications
• OWASP Password Storage Cheat Sheet