salad-passwords

Opinionated Argon2id password hashing and verification utilities. This package is intentionally small and hostile to misuse. It is not an authentication framework.

Install

npm install salad-passwords

This package targets Node.js >= 18 and relies on the native argon2 dependency.

Usage (ESM)

import {
  hashPassword,
  verifyPassword,
  needsRehash,
  verifyAndRehash,
} from 'salad-passwords';

const hash = await hashPassword('correct horse battery staple');
const ok = await verifyPassword('correct horse battery staple', hash);

if (needsRehash(hash)) {
  const upgraded = await hashPassword('correct horse battery staple');
  // store upgraded
}

const result = await verifyAndRehash('correct horse battery staple', hash);
if (result.valid && result.newHash) {
  // store result.newHash
}

Usage (CommonJS)

const {
  hashPassword,
  verifyPassword,
  needsRehash,
  verifyAndRehash,
} = require('salad-passwords');

Guide

Create and store a hash

const hash = await hashPassword(userPassword);
// store `hash` in your database

Verify a login

const ok = await verifyPassword(userPassword, storedHash);
if (!ok) {
  // deny login
}

Verify and transparently upgrade

const result = await verifyAndRehash(userPassword, storedHash);
if (!result.valid) {
  // deny login
} else if (result.newHash) {
  // store result.newHash
}

Manual upgrade check

if (needsRehash(storedHash)) {
  const upgraded = await hashPassword(userPassword);
  // store upgraded
}

API

hashPassword(password, options?)

Returns a self-describing hash string using Argon2id.

Options (all optional, must be integers):

• memoryCost (default 65536, min 8)
• timeCost (default 3, min 2)
• parallelism (default 4, min 1)
• hashLength (default 32, min 1)
• saltLength (default 16, min 1)

Invalid options throw a TypeError or RangeError.

verifyPassword(password, storedHash)

Returns true if the password matches the hash, otherwise false. Invalid or corrupted hashes fail safely.

needsRehash(storedHash)

Returns true if the hash uses weaker parameters or an older format.

verifyAndRehash(password, storedHash)

Returns { valid: boolean; newHash?: string }.

Hash Format

$salad-passwords$v1$argon2id$m=<m>,t=<t>,p=<p>$<salt>$<hash>

The format is versioned and fully self-describing. New versions will continue to read old hashes.

Non-Goals

No user management, sessions, tokens, strength checks, or storage helpers.