Verdaccio Htpasswd Authentication Plugin

Common errors

• Error: EACCES: permission denied, open './htpasswd'

  cause Verdaccio does not have write permissions to create or update the specified htpasswd file.
  fix Ensure the directory containing the `htpasswd` file, and the file itself, has appropriate read/write permissions for the user running the Verdaccio process. For example, `chown verdaccio_user:verdaccio_group /path/to/htpasswd_file` and `chmod 600 /path/to/htpasswd_file`.

• npm adduser fails or results in 'You don't have enough permission to perform this action'

  cause The `max_users` setting in `config.yaml` is set to a specific number (or -1 to disable registration) and the limit has been reached, or registration is disabled. Alternatively, the Verdaccio URL in the `npm adduser` command is incorrect.
  fix Check the `max_users` setting in `config.yaml`. If you intend to allow more users or enable registration, ensure it's not set to -1 or a low number. Also, verify that the `npm adduser --registry <URL>` command uses the correct URL for your Verdaccio instance.

• Users cannot log in despite correct htpasswd entries

  cause The 'algorithm' or 'rounds' settings in 'config.yaml' for the htpasswd plugin do not match the algorithm/rounds used to generate the passwords in the 'htpasswd' file.
  fix Ensure that the `algorithm` and `rounds` configured in your `config.yaml` match exactly how the passwords were generated in your `htpasswd` file. If you change these settings in Verdaccio, you may need to regenerate user passwords using the new algorithm/rounds.

Warnings

• gotcha Using a high 'rounds' value for the 'bcrypt' algorithm (default is 10) significantly increases CPU usage during password verification. This can lead to increased latency and performance issues in Verdaccio instances handling a large volume of authenticated requests. Conversely, a value too low increases brute-force attack risk.
  Fix: Carefully balance the 'rounds' value in your `config.yaml`. The default of 10 is generally a good starting point. Monitor CPU usage under load and adjust as necessary for your environment's security and performance requirements. Consider using hardware with AES-NI for better bcrypt performance.
• deprecated Verdaccio 5.x running on Node.js versions 21 or lower might emit `[DEP0106] DeprecationWarning: crypto.createDecipher is deprecated` if the default legacy token signature is enabled. This is due to a deprecated Node.js API used by Verdaccio's legacy token handling.
  Fix: Upgrade your Node.js environment to version 22 or higher, where a modern legacy signature implementation addresses this warning. Alternatively, review Verdaccio's token signature configuration for options to disable the legacy token signature if not strictly required.
• breaking Verdaccio v6.0.0 (the core registry, not this plugin directly) dropped support for Node.js 16. While verdaccio-htpasswd itself is at version 10.x, it runs within a Verdaccio instance. Therefore, upgrading Verdaccio to v6.0.0 will require a minimum Node.js version of 18 or higher.
  Fix: Ensure your Node.js environment is updated to at least Node.js 18 before upgrading your Verdaccio instance to v6.x or newer versions.

Install

• npm install verdaccio-htpasswd npm
• yarn add verdaccio-htpasswd yarn
• pnpm add verdaccio-htpasswd pnpm

Imports

• Auth
  wrong:

  const Auth = require('verdaccio-htpasswd');

  correct:

  import Auth from 'verdaccio-htpasswd';

  While this package ships TypeScript types and supports ESM, `verdaccio-htpasswd` is primarily used via Verdaccio's `config.yaml` for configuration, not direct programmatic import by end-user applications. This import style would be for advanced plugin developers or testing.
• IAuthModule

  import type { IAuthModule } from '@verdaccio/types';

  This is a type import for developers extending or implementing Verdaccio authentication modules, providing the interface definition for how auth plugins interact with Verdaccio. This module implements this interface implicitly.
• Auth
  wrong:

  import Auth from 'verdaccio-htpasswd';

  correct:

  const Auth = require('verdaccio-htpasswd');

  CommonJS `require` is still supported by Verdaccio for plugins. This pattern might be seen in older custom plugin implementations or test setups. For new development, ESM `import` is preferred when possible.

Quickstart

This configuration snippet for `config.yaml` enables `verdaccio-htpasswd` as the authentication backend, specifies the path to the htpasswd file, sets the hashing algorithm to bcrypt with 10 rounds, and defines package access permissions based on authentication status.

auth:
  htpasswd:
    file: ./htpasswd
    # Maximum amount of users allowed to register, defaults to "+infinity".
    # Set to -1 to disable registration via `npm adduser`.
    # max_users: 1000
    # Hash algorithm, possible options are: "bcrypt", "md5", "sha1", "crypt".
    # Default algorithm is crypt, but 'bcrypt' is recommended for new installations.
    algorithm: bcrypt
    # Rounds number for "bcrypt", ignored for other algorithms.
    # Setting this higher increases security but also CPU usage during verification.
    rounds: 10

# Example package access configuration using htpasswd authentication
packages:
  '@*/*':
    access: $authenticated # Only authenticated users can access scoped packages
    publish: $authenticated # Only authenticated users can publish scoped packages
  '**':
    access: $all          # All users (including anonymous) can access public packages
    publish: $authenticated # Only authenticated users can publish public packages