Registry / web-framework / verdaccio-htpasswd

verdaccio-htpasswd

library10.5.5jsnpmunverified

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.

web-framework auth-security devops

npm install verdaccio-htpasswd

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VERDACCIO-HTPASSWD

verdaccio-htpasswd

web-frameworkjavascriptv10.5.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Auth

✓ import Auth from 'verdaccio-htpasswd';

✗ const Auth = require('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

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

✗ import Auth from '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.

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

Debug

Known issues

gotchaUsing 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.

affects: >=1.0.0

deprecatedVerdaccio 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.

affects: >=5.0.0

breakingVerdaccio 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.

affects: >=6.0.0 (for Verdaccio core)

Errors

Common errors & fixes

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

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'

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

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.

Upgrade

Version history

10.5.5latest on npm

Audit

Dependencies

verdacciorequiredRuntime peer dependency; verdaccio-htpasswd is an authentication plugin for Verdaccio.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

githubhttps://github.com/verdaccio/verdaccio ↗

packagehttps://www.npmjs.com/package/verdaccio-htpasswd ↗

homepagehttps://verdaccio.org ↗