mirror of
https://github.com/verdaccio/verdaccio.git
synced 2024-12-16 21:56:25 -05:00
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# 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.
|