argon2

node-argon2 exposes the reference Argon2 implementation (winner of the Password Hashing Competition) to Node.js via native bindings, so applications can hash and verify passwords with sensible, security-recommended defaults instead of hand-rolling parameters. It supports all three Argon2 variants (argon2i, argon2d, and the default argon2id) and produces PHC-formatted hash strings that embed the algorithm parameters, making stored hashes self-describing and easy to verify or upgrade later.

The library ships prebuilt native binaries for the most common OS/architecture combinations (Linux, macOS, Windows, Alpine, FreeBSD across x86-64 and ARM) so most installs avoid a local compile step, falling back to node-gyp when no matching prebuild exists. On top of hashing and verifying, it can detect whether an existing hash needs rehashing after a parameter change, and a TypeScript declaration file ships with the package for typed usage out of the box.

What You Get

• argon2.hash() and argon2.verify() async functions with sensible, security-team-recommended defaults for memory cost, time cost, and parallelism
• Support for all three Argon2 variants (argon2i, argon2d, argon2id) selectable via a simple type option
• PHC-formatted output strings that embed the algorithm and parameters, so a stored hash is self-describing and portable
• needsRehash() helper to detect when a stored hash’s parameters are out of date and should be regenerated
• Prebuilt native binaries for Linux, macOS, Windows, Alpine, and FreeBSD across x86-64/ARM64/ARMv7, avoiding a local C++ toolchain for most users
• Bundled TypeScript type declarations for typed usage without extra @types packages

Common Use Cases

• Hashing user passwords at signup and verifying them at login in a Node.js backend, without hand-tuning Argon2 parameters
• Migrating an application off bcrypt or PBKDF2 to a more modern, memory-hard hashing algorithm
• Detecting and transparently rehashing older, weaker-parameter password hashes on next successful login via needsRehash()
• Deriving secret material or associated-data-bound hashes for authentication tokens using Argon2’s secret/associatedData options

Under The Hood

Architecture: The published package is a thin JS wrapper (argon2.cjs) around a native N-API addon; the wrapper handles salt generation via node:crypto’s randomBytes, PHC-string serialization/deserialization via the @phc/format package, and exposes hash/verify/needsRehash as promise-returning functions built on top of the synchronous native hash binding loaded through node-gyp-build. The actual Argon2 algorithm itself lives in vendored C source under argon2/src (from the reference P-H-C/phc-winner-argon2 implementation), compiled via binding.gyp into a native addon that the JS layer calls into.

Tech Stack: JavaScript (CommonJS, type: commonjs) for the public API, C for the vendored Argon2 core, built with node-gyp/prebuildify and distributed with prebuilt .node binaries per platform via node-gyp-build at install time. Runtime dependencies are minimal: @phc/format for PHC string handling and node-addon-api/node-gyp-build for the native binding glue. The project requires Node >=22.0.0 and uses modern tooling (oxlint, oxfmt, TypeScript 7) for development.

Code Quality: test.cjs (237 lines) runs via Node’s built-in test runner and exercises hash/verify round-trips, option handling, and error paths; this is reasonably thorough for a small native-binding wrapper, though the bulk of the actual cryptographic logic lives in the vendored, separately-audited Argon2 C source rather than in this repo’s own tests. Naming is consistent and the JS wrapper is documented with JSDoc typedefs and overloads that also drive the generated TypeScript types.

API Design: The public surface is deliberately small — hash, verify, needsRehash, and a handful of named constants for the three Argon2 variants — with security-conscious defaults so most callers never need to touch tuning parameters at all. JSDoc-driven TypeScript overloads mean hash(password, {raw: true}) and the default encoded-string form are both properly typed without a separate .d.ts maintenance burden, keeping the developer experience low-friction for the common case while still exposing the full parameter set for advanced use.