{"id":16699,"library":"verdaccio-htpasswd","title":"Verdaccio Htpasswd Authentication Plugin","description":"verdaccio-htpasswd is the official and default authentication plugin for Verdaccio, a lightweight private npm proxy registry. It enables user authentication by leveraging standard Apache `htpasswd` files, making it a simple yet effective solution for managing access to private packages. The package is currently at version 10.5.5 and is actively maintained as part of the Verdaccio monorepo, receiving updates in alignment with Verdaccio's release cycle (e.g., it was updated alongside Verdaccio 5.24.0). Its primary differentiator is its seamless, built-in integration with Verdaccio, offering file-based user management, support for various hashing algorithms including bcrypt, MD5, SHA1, and crypt, and an easy configuration process. It's ideal for private registries where a full-fledged database-backed authentication system is overkill, providing a straightforward approach to user registration and login.","status":"active","version":"10.5.5","language":"javascript","source_language":"en","source_url":"https://github.com/verdaccio/monorepo","tags":["javascript","verdaccio","plugin","auth","htpasswd","typescript"],"install":[{"cmd":"npm install verdaccio-htpasswd","lang":"bash","label":"npm"},{"cmd":"yarn add verdaccio-htpasswd","lang":"bash","label":"yarn"},{"cmd":"pnpm add verdaccio-htpasswd","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency; verdaccio-htpasswd is an authentication plugin for Verdaccio.","package":"verdaccio","optional":false}],"imports":[{"note":"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.","wrong":"const Auth = require('verdaccio-htpasswd');","symbol":"Auth","correct":"import Auth from 'verdaccio-htpasswd';"},{"note":"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.","symbol":"IAuthModule","correct":"import type { IAuthModule } from '@verdaccio/types';"},{"note":"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.","wrong":"import Auth from 'verdaccio-htpasswd';","symbol":"Auth","correct":"const Auth = require('verdaccio-htpasswd');"}],"quickstart":{"code":"auth:\n  htpasswd:\n    file: ./htpasswd\n    # Maximum amount of users allowed to register, defaults to \"+infinity\".\n    # Set to -1 to disable registration via `npm adduser`.\n    # max_users: 1000\n    # Hash algorithm, possible options are: \"bcrypt\", \"md5\", \"sha1\", \"crypt\".\n    # Default algorithm is crypt, but 'bcrypt' is recommended for new installations.\n    algorithm: bcrypt\n    # Rounds number for \"bcrypt\", ignored for other algorithms.\n    # Setting this higher increases security but also CPU usage during verification.\n    rounds: 10\n\n# Example package access configuration using htpasswd authentication\npackages:\n  '@*/*':\n    access: $authenticated # Only authenticated users can access scoped packages\n    publish: $authenticated # Only authenticated users can publish scoped packages\n  '**':\n    access: $all          # All users (including anonymous) can access public packages\n    publish: $authenticated # Only authenticated users can publish public packages","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0 (for Verdaccio core)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"Verdaccio does not have write permissions to create or update the specified htpasswd file.","error":"Error: EACCES: permission denied, open './htpasswd'"},{"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.","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.","error":"npm adduser fails or results in 'You don't have enough permission to perform this action'"},{"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.","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.","error":"Users cannot log in despite correct htpasswd entries"}],"ecosystem":"npm"}