Prevent Argon2 verify crashes by validating password hashes

by

Summary

A production service failed during user authentication due to a TypeError thrown by the argon2 library. The error pchstr must be a non-empty string indicates that the function responsible for verifying a password received an undefined, null, or empty string in place of the stored hash. This is a classic case of data integrity failure where the application logic assumes a valid hash exists in the database, but the actual value retrieved is invalid.

Root Cause

The crash was triggered by a mismatch in the arguments passed to argon2.verify(hash, password). Specifically:

  • Invalid Hash Argument: The hash parameter passed to the verify function was not a valid PHC-formatted string.
  • Argument Swapping: In many common mistakes, developers accidentally swap the order of arguments, passing the plain-text password where the hash is expected.
  • Database Nullability: The code attempted to verify a password against a user record where the password_hash column was either null or an empty string (e.g., a newly registered user who hasn’t had a hash generated yet).
  • Library Validation: The underlying @phc/format library performs strict validation to prevent security vulnerabilities (like timing attacks or injection) and throws a TypeError if the input does not meet the required format.

Why This Happens in Real Systems

In distributed production environments, this error rarely stems from the library itself and almost always from upstream data issues:

  • Race Conditions: A user attempts to log in immediately after registration, but the database write for the hash hasn’t fully propagated or committed due to eventual consistency in distributed databases.
  • Failed Migrations: A database schema change or a botched data migration left certain user rows with empty password fields.
  • Unchecked API Inputs: An Express middleware failed to validate that a user object actually contained a hash before passing it to the authentication service.
  • Implicit Type Coercion: JavaScript’s dynamic typing allows undefined to be passed into functions, which only fails once the code reaches the strict type-checking layer of a native C++ binding like argon2.

Real-World Impact

  • Service Instability: If the error is not caught in a try/catch block, it triggers an uncaught exception, potentially crashing the entire Node.js process and causing a service outage.
  • Authentication Denial of Service (DoS): Legitimate users are unable to log in if their account data is corrupted, leading to increased support tickets and user churn.
  • Security Blind Spots: If the error is swallowed without proper logging, it can mask larger issues, such as a database corruption event or an attacker attempting to probe for null-value vulnerabilities.

Example or Code (if necessary and relevant)

const argon2 = require('argon2');

async function verifypassword(password, hash) {
  // THE FIX: Defensive programming to ensure the hash is valid before calling the library
  if (!hash || typeof hash !== 'string' || hash.length === 0) {
    console.error("Critical: Attempted to verify password against an invalid hash.");
    return false; 
  }

  try {
    return await argon2.verify(hash, password);
  } catch (err) {
    console.error("Argon2 verification failed:", err.message);
    return false;
  }
}

// Scenario 1: The Crash (What happened in the report)
// verifypassword("password123", undefined); 

// Scenario 2: The Safe Implementation
async function safeRun() {
  const result = await verifypassword("muzaif", ""); // Returns false instead of crashing
  console.log("Verification result:", result);
}

safeRun();

How Senior Engineers Fix It

Senior engineers focus on defensive programming and system observability:

  • Input Validation: Implementing strict schema validation (using tools like Joi or Zod) at the edge of the application to ensure only valid data reaches the business logic.
  • Graceful Error Handling: Wrapping third-party library calls in try/catch blocks to ensure that a single malformed data point cannot crash the entire process.
  • Data Integrity Constraints: Enforcing NOT NULL constraints at the database level to prevent empty hashes from ever being persisted.
  • Comprehensive Logging: Implementing structured logging that captures the context of the failure (e.g., the User ID involved) without logging the sensitive plain-text password itself.
  • Circuit Breakers: In complex microservices, using patterns to prevent a single failing dependency from cascading through the system.

Why Juniors Miss It

  • Happy Path Bias: Juniors often write code assuming the database will always return exactly what they expect (the “Happy Path”), ignoring the possibility of null or undefined values.
  • Lack of Boundary Awareness: They treat third-party modules as “black boxes” and assume the library will handle bad input gracefully, rather than realizing that strict libraries throw errors to prevent security breaches.
  • Undefined Error Handling: They often forget that in Node.js, an unhandled promise rejection or an uncaught exception is a fatal event that can bring down a whole container.
  • Ignoring Type Safety: Without TypeScript, juniors may not realize that the type of a variable can change significantly between the database query and the function execution.

Leave a Comment