Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: add migration notes from v5 to master branch
- Loading branch information
1 parent
c17ee46
commit 84373c4
Showing
1 changed file
with
76 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
# Migration guide from Verdaccio 5 to Verdaccio 6 | ||
|
||
Notes regarding breaking changes for next major release. | ||
|
||
> This list might growth over the 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. | ||
|
||
```js | ||
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. | ||
#### 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 |