Migration Guide from Verdaccio 5 to Verdaccio 6

Notes regarding breaking changes for next major release.

This list might growth over the course of development.

Breaking Changes

New node-api interface #2165

If you are using the node-api, the new structure is Promise based and less arguments.

import { runServer } from '@verdaccio/node-api';
// or
import { runServer } from 'verdaccio';
const app = await runServer(); // default configuration
const app = await runServer('./config/config.yaml');
const app = await runServer({ configuration });
app.listen(4000, (event) => {
  // do something
});

Allow other password hashing algorithms #1917

The current implementation of the htpasswd module supports multiple hash formats on verify, but only crypt on sign in. crypt is an insecure old format, so to improve the security of the new verdaccio release we introduce the support of multiple hash algorithms on sign in step.

New hashing algorithms

The new possible hash algorithms to use are bcrypt, md5, sha1. bcrypt is chosen as a default, because of its customizable complexity and overall reliability. You can read more about them here.

Two new properties are added to auth section in the configuration file:

algorithm to choose the way you want to hash passwords.
rounds is used to determine bcrypt complexity. So one can improve security according to increasing computational power.

Example of the new auth config file section:

auth:
htpasswd:
  file: ./htpasswd
  max_users: 1000
  # Hash algorithm, possible options are: "bcrypt", "md5", "sha1", "crypt".
  algorithm: bcrypt
  # Rounds number for "bcrypt", will be ignored for other algorithms.
  rounds: 10

Refactor config module, experiments renamed to flags #1996

The experiments configuration is renamed to flags. The functionality is exactly the same.

flags:
  token: false;
  search: false;

The self_path property from the config file is being removed in favor of config_file full path.
Refactor config module, better types and utilities

Legacy token signature by removing crypto.createDecipher is deprecated #1953

Replace signature handler for legacy tokens by removing deprecated crypto.createDecipher by createCipheriv
The new signature invalidates all previous tokens generated by Verdaccio 5 or previous versions.
The secret key must have 32 characters long

Remediation, update .verdaccio-db.json secret field with a secret key with 32 characters.

Legacy token secret length

If the migration to v6 include an update to node 22 or higher, be aware that token secrets with a length other than 32 are not supported anymore. A new secret will be generated. See docs for more details.

New environment variables

Introduce environment variables for legacy tokens.

VERDACCIO_LEGACY_ALGORITHM: Allows to define the specific algorithm for the token signature which by default is aes-256-ctr
VERDACCIO_LEGACY_ENCRYPTION_KEY: By default, the token stores in the database, but using this variable allows to get it from memory

@verdaccio/commons-api migration

The package has been removed in favor of @verdaccio/core with a similar API, check API documentation for further details.

3.6 KiB Raw Permalink Blame History