verdaccio/docs/migration-v5-to-v6.md

# 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](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`
- `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.