Why Argon Fortress?

| Feature | bcryptjs | argon2-password | | --- | --- | --- | | Algorithm | Bcrypt (1999) | Argon2id (2015 PHC Winner) | | Password length | ❌ Limited to 72 chars | ✅ Unlimited | | GPU/ASIC resistance | ⚠️ Moderate | ✅ Maximum (memory-hard) | | Secret Pepper | ❌ Manual setup | ✅ Smart auto-loading | | Zero-config | ❌ Requires setup | ✅ Works out of the box | | ESM + CJS | ⚠️ Varies | ✅ Dual module support |

Argon2id is the winner of the Password Hashing Competition and is recommended by OWASP for all new applications.

📦 Installation

npm install argon2-password

yarn add argon2-password

pnpm add argon2-password

🚀 Quick Start

import { secureHash, secureVerify, isStrong } from 'argon2-password';

// 1. Validate the password
const check = isStrong('MyP@ssw0rd!123');
if (!check.strong) {
  console.log('Weak password:', check.errors);
  process.exit(1);
}

// 2. Hash it (zero-config — works immediately!)
const hash = await secureHash('MyP@ssw0rd!123');
// => "$argon2id$v=19$m=65536,t=4,p=2$..."

// 3. Verify it later
const isValid = await secureVerify('MyP@ssw0rd!123', hash);
// => true

That's it. No configuration files. No environment variables required. It just works.

🔑 Smart Pepper — Dual-Layer Security

Argon Fortress uses a "Smart Loader" to automatically find and apply a secret pepper to every hash. This adds an extra layer of security on top of the salt that Argon2 already generates.

How the Smart Loader Works

The pepper is resolved in this priority order:

1. 🥇 Pepper passed directly in function arguments
2. 🥈 process.env.AUTH_SECRET environment variable
3. 🥉 Machine-derived fallback (development convenience — NOT for production)

⚠️ The fallback pepper is derived from your machine's hostname, OS user, architecture, and platform. It ensures the library never crashes without config, but it is not a substitute for a real secret. Always set AUTH_SECRET in production.

// Priority 1 — Explicit pepper (highest priority)
const hash = await secureHash('password', { pepper: 'my-secret' });

// Priority 2 — Uses process.env.AUTH_SECRET automatically
const hash = await secureHash('password');

// Priority 3 — Uses machine-derived fallback if nothing else is set
// (works, but NOT recommended for production)
const hash = await secureHash('password');

Detecting Fallback Mode

Use isFallbackPepperActive() in your app startup to warn when no real secret is configured:

import { isFallbackPepperActive } from 'argon2-password';

if (isFallbackPepperActive()) {
  console.warn(
    '⚠️  [argon2-password] No AUTH_SECRET set — using fallback pepper.',
    'Set AUTH_SECRET in your environment for production security.',
  );
}

🛡️ Setting Up Your Secret Key (Optional but Recommended)

To make your passwords virtually impossible to crack — even if your entire database is leaked — add a private secret key to your server.

Step 1: Create a .env file

Create a file named .env in your project's root folder:

# ⚠️ Change this to something unique and random for your app!
AUTH_SECRET=p@ss_W0rd_S3cr3t_99_XYZ_KeepThisPrivate

Step 2: Load it in your app

Use a package like dotenv to load your .env file:

import 'dotenv/config'; // Load .env at the very top
import { secureHash, secureVerify } from 'argon2-password';

// AUTH_SECRET is now automatically used as the pepper!
const hash = await secureHash(userPassword);

Step 3: Add .env to your .gitignore

# NEVER commit your secret key to source control!
.env

Why should I do this?

| Setup | Security Level | What happens if DB is leaked? | | --- | --- | --- | | Without .env | 🟠 Moderate | Argon2id is still very hard to brute-force, but the fallback pepper is machine-derived — an attacker on the same machine could reconstruct it. Not recommended for production. | | With .env | 🟢 Maximum | Passwords are hashed with your private, app-specific key. Even if a hacker steals your database AND your source code, they cannot crack the passwords without this specific .env file from your server. |

📖 API Reference

secureHash(password, options?)

Hash a plaintext password using Argon2id.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | password | string | ✅ | The plaintext password to hash | | options.pepper | string | ❌ | Custom pepper (overrides env/fallback) | | options.memoryCost | number | ❌ | Memory in KiB, 1024–4194304 (default: 65536 = 64MB) | | options.timeCost | number | ❌ | Iterations, 1–100 (default: 4) | | options.parallelism | number | ❌ | Parallelism, 1–16 (default: 2) | | options.hashLength | number | ❌ | Hash length in bytes, 4–128 (default: 32) |

Throws: ArgonOptionsError if any tuning parameter is outside the allowed range.

Returns: Promise<string> — The encoded Argon2id hash.

const hash = await secureHash('MyP@ssw0rd!123');
const hash2 = await secureHash('MyP@ssw0rd!123', {
  pepper: 'custom-key',
  memoryCost: 131072, // 128 MB
  timeCost: 6,
});

secureVerify(password, hash, options?)

Verify a plaintext password against a stored Argon2id hash.

Tuning parameters (memory, time, parallelism, hashLength) are embedded in the hash itself — only pepper is needed for verification.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | password | string | ✅ | The plaintext password to verify | | hash | string | ✅ | The stored Argon2id hash string | | options.pepper | string | ❌ | Must match the pepper used during hashing |

Returns: Promise<boolean> — true if valid, false otherwise.

Throws: VerificationError if an operational error occurs (native binding failure, OOM, etc.). A password mismatch or malformed hash returns false without throwing.

import { secureVerify, VerificationError } from 'argon2-password';

try {
  const isValid = await secureVerify('MyP@ssw0rd!123', storedHash);
} catch (err) {
  if (err instanceof VerificationError) {
    console.error('System error during verification:', err.message);
    // err.cause contains the original argon2 error
  }
}

⚠️ Important: You must use the same pepper for verification that was used during hashing. If you change your AUTH_SECRET, old hashes will no longer verify.

isStrong(password)

Validate password strength. Script-agnostic — adapts based on the characters used:

• Cased scripts (Latin, Cyrillic, Greek): Requires mixed case.
• Caseless scripts (CJK, Arabic, Thai): Case requirements waived.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | password | string | ✅ | The password to evaluate |

Returns: { strong: boolean, errors: string[] }

| Rule | Requirement | | --- | --- | | Minimum length | At least 10 characters (by codepoint) | | Letter | At least 1 Unicode letter (\p{L}) | | Mixed case | Required only if cased characters are present | | Digit | At least 1 digit (any script) | | Special character | At least 1 non-letter, non-digit character |

isStrong('MyP@ssw0rd!123');     // { strong: true, errors: [] }
isStrong('密码很强的测试安全好1!');  // { strong: true, errors: [] }
isStrong('abc123');              // { strong: false, errors: [...] }

🏗️ Full Example — Express.js Auth

import 'dotenv/config';
import express from 'express';
import { secureHash, secureVerify, isStrong } from 'argon2-password';

const app = express();
app.use(express.json());

// Sign Up
app.post('/register', async (req, res) => {
  const { email, password } = req.body;

  // Validate password strength
  const strength = isStrong(password);
  if (!strength.strong) {
    return res.status(400).json({ errors: strength.errors });
  }

  // Hash and store
  const hash = await secureHash(password);
  // await db.users.create({ email, passwordHash: hash });

  res.json({ message: 'Account created!' });
});

// Login
app.post('/login', async (req, res) => {
  const { email, password } = req.body;

  // const user = await db.users.findByEmail(email);
  const user = { passwordHash: '...' }; // placeholder

  const isValid = await secureVerify(password, user.passwordHash);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  res.json({ message: 'Login successful!' });
});

app.listen(3000);

🔬 How It Works Under the Hood

┌──────────────────────────────────────────────────────────┐
│                     User's Password                      │
│                    "MyP@ssw0rd!123"                       │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────┐
│              🔐 Smart Pepper Loader                      │
│                                                          │
│   1. Check function args  →  pepper found? Use it.       │
│   2. Check AUTH_SECRET    →  env var set?  Use it.        │
│   3. Machine-derived fallback → dev convenience only.     │
│                                                          │
│   Pepper → SHA-256 → 32-byte secret key                  │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────┐
│              ⚙️  Argon2id Engine                         │
│                                                          │
│   • Memory:      64 MB  (resists GPU attacks)            │
│   • Iterations:  4      (resists brute-force)            │
│   • Parallelism: 2      (uses multi-core)                │
│   • Salt:        auto   (unique per hash)                │
│   • Secret:      pepper (from Smart Loader)              │
└──────────────────┬───────────────────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────┐
│              📦 Output                                   │
│  "$argon2id$v=19$m=65536,t=4,p=2$<salt>$<hash>"         │
└──────────────────────────────────────────────────────────┘

⚙️ Module Support

This package ships as both ESM and CommonJS, so it works everywhere:

// ESM (import)
import { secureHash, secureVerify, isStrong } from 'argon2-password';

// CommonJS (require)
const { secureHash, secureVerify, isStrong } = require('argon2-password');

🧪 Testing

npm test

📄 License

MIT © Deepak Kumar