htpasswd

Common errors

• htpasswd: command not found

  cause The `htpasswd` CLI tool has not been installed globally or is not in your system's PATH.
  fix Install the package globally using `npm install -g htpasswd`.

• Error: file already exists

  cause Attempting to create a new htpasswd file using the `-c` option when a file with the same name already exists.
  fix To overwrite an existing file (which will delete all existing users), you must manually remove the old file first or confirm the overwrite via CLI prompt (if available) or programmatic option. If you intend to add a user to an existing file, omit the `-c` flag.

• Password mismatch during verification, even though the password seems correct.

  cause This often happens if the password was originally hashed with an insecure or deprecated algorithm (e.g., MD5, SHA, crypt) or a different bcrypt cost than what is currently being used for verification attempts, or if the password was truncated by an old algorithm.
  fix Ensure that the verification process uses the correct algorithm that matches how the password was originally stored. If using deprecated algorithms, consider migrating users to bcrypt. Check the actual hash in the `.htpasswd` file to confirm the algorithm used (e.g., `$2y$`, `$apr1$`, `$sha1$` prefixes indicate bcrypt, MD5, SHA respectively).

Warnings

• gotcha Using the `-b` option to pass passwords directly on the command line is insecure, as the password becomes visible in shell history and process lists (e.g., `ps aux`).
  Fix: For script usage, utilize the `-i` option to read passwords from `stdin` to prevent exposure. For programmatic use, pass passwords directly to the API methods.
• gotcha The `-d` (crypt), `-s` (SHA), and `-p` (plaintext) encryption algorithms are considered insecure by modern standards. Using them can compromise the security of your authentication.
  Fix: Always prefer the `-B` (bcrypt) option for hashing passwords, which is currently considered very secure. When using bcrypt, ensure the `-C` cost parameter is set appropriately for your security needs (default is 5, but higher values like 10-12 are recommended).
• gotcha When using bcrypt with the `-C` option (cost), note that the default cost of 5 might be too low for high-security applications. Higher costs increase computational time, making brute-force attacks more difficult.
  Fix: Adjust the `-C` parameter to a higher value (e.g., 10-12) to increase the computational cost and enhance security, balancing it with acceptable response times for your system.

Install

• npm install htpasswd npm
• yarn add htpasswd yarn
• pnpm add htpasswd pnpm

Imports

• Htpasswd
  wrong:

  import Htpasswd from 'htpasswd';

  correct:

  import { Htpasswd } from 'htpasswd';

  The `Htpasswd` class provides the main API for programmatic file management. While primarily a CommonJS package, Node.js's interoperability allows this ESM syntax. For strict CommonJS, use `const { Htpasswd } = require('htpasswd');`.
• createHash
  wrong:

  const createHash = require('htpasswd').createHash;

  correct:

  import { createHash } from 'htpasswd';

  A direct utility function for hashing a password, exported alongside the `Htpasswd` class. For CommonJS: `const { createHash } = require('htpasswd');`.
• CommonJS named exports

  const { Htpasswd, createHash, verifyPassword } = require('htpasswd');

  For CommonJS environments, multiple named exports like `Htpasswd`, `createHash`, and `verifyPassword` can be destructured directly from the main package export.

Quickstart

This quickstart demonstrates programmatic usage of the `htpasswd` library to create a new password file, add a user with bcrypt encryption, verify passwords, and delete the user.

import { Htpasswd } from 'htpasswd';
import * as path from 'path';
import * as fs from 'fs/promises';

async function runHtpasswdExample() {
  const filePath = path.join(__dirname, 'example.htpasswd');
  const username = 'testuser';
  const password = 'securePassword123';
  const wrongPassword = 'wrongPassword';

  try {
    // 1. Create a new htpasswd file and add a user (using bcrypt by default)
    // Default bcrypt cost is 5. Using 10 here for better security.
    const htpasswd = new Htpasswd(filePath, { create: true, bcrypt: true, cost: 10 });
    await htpasswd.add(username, password);
    console.log(`User '${username}' added to '${filePath}' with bcrypt hash.`);
    const content = await fs.readFile(filePath, 'utf8');
    console.log('File content:\n', content);

    // 2. Verify the correct password
    const isCorrect = await htpasswd.verify(username, password);
    console.log(`Password for '${username}' is correct: ${isCorrect}`);

    // 3. Try to verify with a wrong password
    const isWrong = await htpasswd.verify(username, wrongPassword);
    console.log(`Password for '${username}' with wrong input: ${isWrong}`);

    // 4. Delete the user
    await htpasswd.delete(username);
    console.log(`User '${username}' deleted from '${filePath}'.`);
    const updatedContent = await fs.readFile(filePath, 'utf8');
    console.log('File content after deletion:\n', updatedContent);

  } catch (error: any) {
    console.error('Error during htpasswd operations:', error.message);
  } finally {
    // Clean up the created file
    try {
      await fs.unlink(filePath);
      console.log(`Cleaned up '${filePath}'.`);
    } catch (e) {
      // Ignore if file doesn't exist or permissions issue during cleanup
    }
  }
}

runHtpasswdExample();