Password Hashing

/**
 * Hashes a password into a string format suitable for storage
 * @param password - The password to hash (string or Uint8Array)
 * @param opsLimit - CPU/time cost parameter (higher = more secure, slower)
 * @param memLimit - Memory cost parameter in bytes (higher = more secure, more memory)
 * @returns String-encoded hash suitable for database storage
 */
function crypto_pwhash_str(password, opsLimit, memLimit);

/**
 * Verifies a password against its stored hash
 * @param hashed_password - String-encoded hash from crypto_pwhash_str
 * @param password - Password to verify
 * @returns true if password matches, false otherwise
 */
function crypto_pwhash_str_verify(hashed_password, password);

/**
 * Checks if a stored hash needs rehashing with updated parameters
 * @param hashed_password - String-encoded hash to check
 * @param opsLimit - Current recommended CPU cost
 * @param memLimit - Current recommended memory cost
 * @returns true if hash should be updated, false if current parameters are sufficient
 */
function crypto_pwhash_str_needs_rehash(hashed_password, opsLimit, memLimit);

/**
 * Derives a key from a password using Argon2
 * @param keyLength - Length of derived key in bytes
 * @param password - Password to derive from
 * @param salt - 16-byte salt (must be unique per password)
 * @param opsLimit - CPU/time cost parameter
 * @param memLimit - Memory cost parameter in bytes
 * @param algorithm - Algorithm to use (ALG_ARGON2I13 or ALG_ARGON2ID13)
 * @returns Derived key of specified length
 */
function crypto_pwhash(keyLength, password, salt, opsLimit, memLimit, algorithm);

// Hash a password for storage
const password = "user_password_123";
const hash = sodium.crypto_pwhash_str(
  password,
  sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
  sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE
);

console.log(hash); // "$argon2id$v=19$m=65536,t=2,p=1$..."

// Verify password during login
const isValid = sodium.crypto_pwhash_str_verify(hash, password);
console.log(isValid); // true

// Check if rehashing is needed (e.g., after upgrading security parameters)
const needsRehash = sodium.crypto_pwhash_str_needs_rehash(
  hash,
  sodium.crypto_pwhash_OPSLIMIT_SENSITIVE,
  sodium.crypto_pwhash_MEMLIMIT_SENSITIVE
);

if (needsRehash) {
  const newHash = sodium.crypto_pwhash_str(
    password,
    sodium.crypto_pwhash_OPSLIMIT_SENSITIVE,
    sodium.crypto_pwhash_MEMLIMIT_SENSITIVE
  );
  // Update stored hash in database
}

/**
 * Hashes a password using Scrypt
 * @param password - Password to hash
 * @param opsLimit - CPU/time cost parameter
 * @param memLimit - Memory cost parameter
 * @returns String-encoded Scrypt hash
 */
function crypto_pwhash_scryptsalsa208sha256_str(password, opsLimit, memLimit);

/**
 * Verifies a password against Scrypt hash
 * @param hashed_password - String-encoded Scrypt hash
 * @param password - Password to verify
 * @returns true if password matches, false otherwise
 */
function crypto_pwhash_scryptsalsa208sha256_str_verify(hashed_password, password);

/**
 * Derives a key using Scrypt
 * @param keyLength - Length of derived key
 * @param password - Password to derive from
 * @param salt - 32-byte salt for Scrypt
 * @param opsLimit - CPU/time cost parameter
 * @param memLimit - Memory cost parameter
 * @returns Derived key
 */
function crypto_pwhash_scryptsalsa208sha256(keyLength, password, salt, opsLimit, memLimit);

/**
 * Low-level Scrypt function with full parameter control
 * @param password - Password bytes
 * @param salt - Salt bytes
 * @param opsLimit - CPU cost (N parameter)
 * @param r - Block size parameter
 * @param p - Parallelization parameter
 * @param keyLength - Output key length
 * @returns Derived key
 */
function crypto_pwhash_scryptsalsa208sha256_ll(password, salt, opsLimit, r, p, keyLength);

// Algorithms
const crypto_pwhash_ALG_ARGON2I13 = 1;   // Argon2i (side-channel resistant)
const crypto_pwhash_ALG_ARGON2ID13 = 2;  // Argon2id (recommended, default)
const crypto_pwhash_ALG_DEFAULT = 2;     // Default to Argon2id

// Operation limits (CPU cost)
const crypto_pwhash_OPSLIMIT_INTERACTIVE = 2;    // Fast, for interactive use
const crypto_pwhash_OPSLIMIT_SENSITIVE = 4;      // Slower, for sensitive data

// Memory limits  
const crypto_pwhash_MEMLIMIT_INTERACTIVE = 67108864;  // 64 MB
const crypto_pwhash_MEMLIMIT_SENSITIVE = 268435456;   // 256 MB

// Constraints
const crypto_pwhash_PASSWD_MIN = 0;        // Minimum password length
const crypto_pwhash_PASSWD_MAX = 4294967295; // Maximum password length
const crypto_pwhash_SALTBYTES = 16;        // Salt size for Argon2
const crypto_pwhash_STRBYTES = 102;        // String format length

// Operation limits
const crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_INTERACTIVE = 32768;
const crypto_pwhash_scryptsalsa208sha256_OPSLIMIT_SENSITIVE = 1048576;

// Memory limits  
const crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_INTERACTIVE = 16777216;  // 16 MB
const crypto_pwhash_scryptsalsa208sha256_MEMLIMIT_SENSITIVE = 1073741824; // 1 GB

// Constraints
const crypto_pwhash_scryptsalsa208sha256_SALTBYTES = 32;  // Salt size for Scrypt
const crypto_pwhash_scryptsalsa208sha256_STRBYTES = 102;  // String format length

// Derive encryption key from password
const password = "user_password_123";
const salt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);

const encryptionKey = sodium.crypto_pwhash(
  32,  // 32-byte key
  password,
  salt,
  sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
  sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE,
  sodium.crypto_pwhash_ALG_ARGON2ID13
);

// Store salt with encrypted data for later key derivation