Password hashing best practices

import { hash, verify, Argon2Options } from '@node-rs/argon2';

const ARGON2_CONFIG: Argon2Options = {
  memoryCost: 65536, // 64 MB
  timeCost: 3,       // 3 iterations
  parallelism: 4,    // 4 threads
  hashLength: 32,    // 256-bit output
  version: 19        // Argon2 v1.3
};

export async function hashPassword(plaintext: string): Promise<string> {
  return await hash(plaintext, ARGON2_CONFIG);
}

utput follows the PHC string format: $argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>. This self-describing format eliminates external parameter tracking.

Step 3: Verification

Verification must extract parameters from the stored hash and perform constant-time comparison. The library handles parameter parsing and timing-safe comparison automatically.

export async function verifyPassword(
  plaintext: string,
  storedHash: string
): Promise<boolean> {
  return await verify(storedHash, plaintext);
}

Step 4: Architecture Decisions and Rationale

Parameter Versioning: Store the full PHC string in the database. Do not split salts or parameters into separate columns. The embedded format guarantees forward compatibility and simplifies migration.

Cost Parameter Scaling: Hardware improves continuously. Implement a background monitoring mechanism that measures average hashing latency. When latency drops below 50 ms due to hardware upgrades, increment memoryCost or timeCost in the next deployment.

Migration Strategy: Support multiple algorithms simultaneously. When a user authenticates, verify against the stored hash. If the hash uses a deprecated algorithm or outdated parameters, rehash with the current configuration and update the database. This lazy migration ensures zero downtime and gradual adoption.

export async function authenticateUser(
  plaintext: string,
  storedHash: string
): Promise<{ valid: boolean; needsRehash: boolean }> {
  const isValid = await verifyPassword(plaintext, storedHash);
  
  if (!isValid) return { valid: false, needsRehash: false };
  
  const needsRehash = storedHash.startsWith('$2b$') || 
                      storedHash.startsWith('$2a$') ||
                      !storedHash.includes('m=65536');
                      
  return { valid: true, needsRehash };
}

Storage Separation: Treat the password hash column as high-sensitivity data. Enforce strict database access controls, disable logging of hash values, and never expose the column in API responses or error messages.

Pitfall Guide

1. Using Fast Cryptographic Hashes for Passwords

SHA-256, SHA-3, and BLAKE2 are designed for integrity verification, not credential storage. They execute in microseconds and are heavily optimized for GPU/ASIC parallelization. Using them for passwords guarantees rapid offline cracking once a database is compromised. Always use adaptive, memory-hard functions.

2. Hardcoding Cost Parameters Without Monitoring

Security parameters are not static. A configuration that takes 100 ms on a 2020 server may take 30 ms on a 2025 server. Hardcoding without monitoring reduces effective security over time. Implement latency tracking and schedule parameter reviews quarterly.

3. Implementing Custom Salting or Key Derivation

Manual salting (hash(salt + password)) introduces timing vulnerabilities, reduces entropy, and breaks library optimizations. Modern hashing functions generate 128-bit cryptographically secure salts internally and embed them in the output. Custom implementations rarely match the security guarantees of audited libraries.

4. Ignoring Parameter Versioning in Database Schema

Storing salts, iteration counts, and algorithm identifiers in separate columns creates migration complexity and increases the risk of parameter mismatch during verification. Use self-describing hash strings (PHC format) to eliminate external state dependencies.

5. Implementing Manual Verification Logic

Writing custom comparison logic (hash1 === hash2) introduces timing side-channels that leak partial hash matches. Always use the verification function provided by the cryptographic library, which implements constant-time comparison and parameter-aware validation.

6. Confusing Password Policy with Storage Security

Complexity requirements, rotation schedules, and breach databases improve online authentication security but do not mitigate offline attacks. Weak hashing renders password policy irrelevant once data is exfiltrated. Treat policy and storage as independent security layers.

7. Logging or Exposing Hash Values

Password hashes are not reversible, but they are reusable. Logging hashes, including them in stack traces, or returning them in API responses enables credential stuffing and offline cracking. Treat hashes as opaque, high-sensitivity tokens with strict access boundaries.

Production Bundle

Action Checklist

• Replace all SHA/MD5 password storage with Argon2id or bcrypt
• Configure memory cost ≥ 64 MB and verify hashing latency < 100 ms
• Remove custom salting logic; rely on library-generated salts
• Implement lazy rehashing on successful authentication
• Store full PHC-formatted hash strings in a single database column
• Disable logging and API exposure of hash values
• Schedule quarterly parameter review based on hardware benchmarks
• Enforce strict database column-level access controls

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
New application / MVP	Argon2id with default parameters	Maximum security, PHC format simplifies migration, library support is mature	Low (standard cloud instances handle 64 MB memory cost easily)
Enterprise / Compliance	Argon2id + FIPS-compliant bcrypt fallback	Meets NIST 800-63B, supports legacy system integration during transition	Medium (requires parameter monitoring infrastructure)
Legacy migration	bcrypt → Argon2id lazy upgrade path	Zero downtime, gradual adoption, maintains compatibility during rollout	Low-Medium (database write amplification during rehashing phase)
High-throughput auth	bcrypt with tuned cost	Lower memory footprint reduces RAM pressure, maintains adequate security	Low (optimized for CPU-bound workloads with strict latency budgets)

Configuration Template

// auth/password.config.ts
import { Argon2Options } from '@node-rs/argon2';

export const PASSWORD_HASH_CONFIG = {
  algorithm: 'argon2id',
  options: {
    memoryCost: 65536,
    timeCost: 3,
    parallelism: 4,
    hashLength: 32,
    version: 19
  } as Argon2Options,
  migration: {
    enabled: true,
    legacyAlgorithms: ['$2b$', '$2a$', '$sha256$', '$sha512$'],
    maxRetries: 3,
    timeoutMs: 100
  },
  monitoring: {
    latencyThresholdMs: 50,
    reviewIntervalDays: 90,
    alertOnExceedance: true
  }
} as const;

Quick Start Guide

1. Install dependencies: npm install @node-rs/argon2
2. Create auth/password.ts with the hash and verify functions from the Core Solution section.
3. Replace existing password storage logic with hashPassword() during registration and verifyPassword() during login.
4. Add lazy rehashing logic to your authentication flow to automatically upgrade legacy hashes on successful login.
5. Deploy and monitor average hashing latency; adjust memoryCost if average latency exceeds 100 ms or drops below 50 ms after hardware changes.