Argon2 Hashing for Node.js

Common errors

• Error: The module '\path\to\node_modules\argon2\lib\binding\napi-vX\argon2.node' was compiled against a different Node.js version. ... Module parse failed: Unexpected character '�' (1:0)

  cause The prebuilt binary (or a locally compiled one) is incompatible with your current Node.js version or operating system/architecture.
  fix Ensure your Node.js version meets the package requirements (>=16.17.0, preferably 18/20). If using a non-standard environment or an older `argon2` version, try manually rebuilding: `npx @mapbox/node-pre-gyp rebuild -C ./node_modules/argon2`.

• Argument of type 'Buffer' is not assignable to parameter of type 'string'.

  cause TypeScript 5.7 introduced changes to how `Buffer` types are handled, causing type mismatches with older `argon2` versions that weren't updated for this change.
  fix Upgrade to `argon2@0.43.1` or newer. This version specifically addresses compatibility issues with TypeScript 5.7's `Buffer` type changes.

• Error: Missing symbols, such as `_ZNSt ...` or `undefined symbol: ` (linker errors during compilation/runtime)

  cause Link-Time Optimization (LTO) can sometimes cause symbol resolution issues in certain compilation environments.
  fix Upgrade to `argon2@0.41.0` or newer. This version disables LTO to prevent such symbol-related compilation errors.

• TS2345: Argument of type 'string | Buffer' is not assignable to parameter of type 'string'.

  cause TypeScript definitions in `argon2` prior to v0.41.1 incorrectly typed byte inputs (e.g., `Buffer`) as `any` or had other inconsistencies.
  fix Upgrade to `argon2@0.41.1` or newer to get corrected TypeScript type declarations for inputs like passwords and salts.

Warnings

• breaking Node.js 16 is no longer supported after version 0.31.2 due to its End-of-Life. Users on Node.js 16 will experience build or runtime failures.
  Fix: Upgrade your Node.js runtime to version 18 or 20 (preferably) to ensure compatibility and receive security updates.
• breaking Older versions of `argon2` (<=0.30.3) had a security vulnerability in their dependency `@mapbox/node-pre-gyp`.
  Fix: Update to `argon2@0.31.0` or newer immediately to mitigate the security risk associated with the `node-pre-gyp` dependency.
• gotcha Installing `argon2` on platforms without prebuilt binaries or specific environments requires a global `node-gyp` installation and a compatible C++ compiler (GCC >= 5 / Clang >= 3.3, or Visual Studio 2015+ on Windows).
  Fix: Install `node-gyp` globally (`npm install -g node-gyp`) and ensure you have a suitable C++ toolchain. For macOS, use `brew install gcc`. For manual compilation, you might need to specify `CXX=g++-12 npm install argon2`.
• gotcha Before version 0.40.0, `argon2` did not ship prebuilt binaries for all platforms, leading to frequent compilation issues for users with diverse environments.
  Fix: Upgrade to `argon2@0.40.0` or newer to leverage prebuilt binaries, which significantly reduces installation complexity and build errors for most users.
• gotcha TypeScript type definitions for byte inputs were incorrect (`any` instead of `Buffer`) in versions prior to 0.41.1, leading to type-checking issues.
  Fix: Update to `argon2@0.41.1` or newer to resolve type declaration inconsistencies for byte-related inputs.

Install

• npm install argon2 npm
• yarn add argon2 yarn
• pnpm add argon2 pnpm

Imports

• hash
  wrong:

  import argon2 from 'argon2'; argon2.hash(...);

  correct:

  import { hash } from 'argon2';

  Named import for the 'hash' function, common in ESM and TypeScript. Prefer named imports for clarity.
• verify
  wrong:

  const argon2 = require('argon2'); argon2.verify(...);

  correct:

  import { verify } from 'argon2';

  Named import for the 'verify' function. The `require` syntax is for CommonJS environments.
• argon2 (all exports)
  wrong:

  const { hash, verify } = require('argon2');

  correct:

  import * as argon2 from 'argon2';

  Standard TypeScript/ESM import for all exports under a namespace. For CommonJS, use `const argon2 = require('argon2');` to access methods like `argon2.hash()`.

Quickstart

Demonstrates how to hash a password using default settings, verify a password against a hash, and hash with custom Argon2 parameters.

import { hash, verify } from 'argon2';

async function main() {
  const password = process.env.USER_PASSWORD ?? 'mySecurePassword';
  let hashedPassword: string;

  try {
    // Hash a password with default options (Argon2id)
    hashedPassword = await hash(password);
    console.log('Hashed password:', hashedPassword);

    // Verify a password against a hash
    if (await verify(hashedPassword, password)) {
      console.log('Password matched!');
    } else {
      console.error('Password did not match.');
    }

    // Example of hashing with custom options (e.g., Argon2i, higher memory cost)
    const customHashedPassword = await hash(password, {
      type: 1, // argon2.ArgonType.Argon2i
      memoryCost: 1024,
      timeCost: 4,
      parallelism: 2
    });
    console.log('Custom hashed password:', customHashedPassword);

  } catch (err) {
    console.error('An error occurred:', err);
  }
}

main();