verdaccio/docs/migrations-guide.md

# Migration Guide from Verdaccio v5 and v6 to Verdaccio v7

Notes regarding breaking changes for next major release.

> This list might growth over the course of development.

## Breaking Changes

### New node-api interface [#2165](https://github.com/verdaccio/verdaccio/pull/2165)

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

```js
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](https://github.com/verdaccio/verdaccio/pull/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](https://httpd.apache.org/docs/2.4/misc/password_encryptions.html).

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:

```yaml
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](https://github.com/verdaccio/verdaccio/pull/1996)

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

```yaml
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](https://github.com/verdaccio/verdaccio/pull/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](https://verdaccio.org/docs/6.x/configuration#legacy-token-signature)
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`. The algorithm must be supported by `crypto.createCipheriv` and `crypto.createDecipheriv`.

- `VERDACCIO_LEGACY_ENCRYPTION_KEY`:

  By default, the token are stored in the database, but using this variable allows to get tokens from memory. The length of the key must be 32 characters otherwise will throw an error.

Read more on [nodejs.org](https://nodejs.org/api/crypto.html#crypto_crypto_createcipheriv_algorithm_key_iv_options).

#### @verdaccio/commons-api migration

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