CLI documentation update from CI
npm CLI robot committed
Jul 21, 2022 at 03:03 UTC
55a684e5a790e8262765e413cdab6b0b36c1f7b1
5 files changed
+61
-18
cli/v8
+1
-1
@@ -1 +1 @@
1
-Subproject commit 51b12a085e087609c99befccfd6a98ef8a9919d0
1
+Subproject commit 4c945302fc2aa6854dc014fe31d6f5dfa96f7b52
content/cli/v8/commands/npm-audit.md
+49
-8
@@ -53,14 +53,55 @@ output, it simply changes the command's failure threshold.
53
54
### Audit Signatures
55
56
-This command can also audit the integrity values of the packages in your
57
-tree against any signatures present in the registry they were downloaded
58
-from. npm will attempt to download the keys from `/-/npm/v1/keys` on
59
-each the registry used to download any given package. It will then
60
-check the `dist.signatures` object in the package itself, and verify the
61
-`sig` present there using the `keyid` there, matching it with a key
62
-returned from the registry. The command for this is `npm audit
63
-signatures`
56
+To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.
57
+
58
+Registry signatures can be verified using the following `audit` command:
59
+
60
+```bash
61
+$ npm audit signatures
62
+```
63
+
64
+The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
65
+
66
+1. Signatures are provided in the package's `packument` in each published version within the `dist` object:
67
+
68
+```json
69
+"dist":{
70
+ "..omitted..": "..omitted..",
71
+ "signatures": [{
72
+ "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
73
+ "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
74
+ }]
75
+}
76
+```
77
+
78
+See this [example](https://registry.npmjs.org/light-cycle/1.4.3) of a signed package from the public npm registry.
79
+
80
+The `sig` is generated using the following template: `${package.name}@${package.version}:${package.dist.integrity}` and the `keyid` has to match one of the public signing keys below.
81
+
82
+2. Public signing keys are provided at `registry-host.tld/-/npm/v1/keys` in the following format:
83
+
84
+```
85
+{
86
+ "keys": [{
87
+ "expires": null,
88
+ "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
89
+ "keytype": "ecdsa-sha2-nistp256",
90
+ "scheme": "ecdsa-sha2-nistp256",
91
+ "key": "{{B64_PUBLIC_KEY}}"
92
+ }]
93
+}
94
+```
95
+
96
+Keys response:
97
+
98
+- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
99
+- `keydid`: sha256 fingerprint of the public key
100
+- `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
101
+- `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
102
+- `key`: base64 encoded public key
103
+
104
+See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
105
106
### Audit Endpoints
107
content/cli/v8/configuring-npm/folders.md
+1
-1
@@ -210,7 +210,7 @@ For a graphical breakdown of what is installed where, use `npm ls`.
210
#### Publishing
211
212
Upon publishing, npm will look in the `node_modules` folder. If any of
213
-the items there are not in the `bundledDependencies` array, then they will
213
+the items there are not in the `bundleDependencies` array, then they will
214
not be included in the package tarball.
215
216
This allows a package maintainer to install all of their dependencies
content/cli/v8/configuring-npm/package-json.md
+5
-5
@@ -839,14 +839,14 @@ if the `soy-milk` package is not installed on the host. This allows you to
839
integrate and interact with a variety of host packages without requiring
840
all of them to be installed.
841
842
-### bundledDependencies
842
+### bundleDependencies
843
844
This defines an array of package names that will be bundled when publishing
845
the package.
846
847
In cases where you need to preserve npm packages locally or have them
848
available through a single file download, you can bundle the packages in a
849
-tarball file by specifying the package names in the `bundledDependencies`
849
+tarball file by specifying the package names in the `bundleDependencies`
850
array and executing `npm pack`.
851
852
For example:
@@ -857,7 +857,7 @@ If we define a package.json like this:
857
{
858
"name": "awesome-web-framework",
859
"version": "1.0.0",
860
- "bundledDependencies": [
860
+ "bundleDependencies": [
861
"renderized",
862
"super-streams"
863
]
@@ -870,9 +870,9 @@ can be installed in a new project by executing `npm install
870
awesome-web-framework-1.0.0.tgz`. Note that the package names do not
871
include any versions, as that information is specified in `dependencies`.
872
873
-If this is spelled `"bundleDependencies"`, then that is also honored.
873
+If this is spelled `"bundledDependencies"`, then that is also honored.
874
875
-Alternatively, `"bundledDependencies"` can be defined as a boolean value. A
875
+Alternatively, `"bundleDependencies"` can be defined as a boolean value. A
876
value of `true` will bundle all dependencies, a value of `false` will bundle
877
none.
878
content/cli/v8/using-npm/config.md
+5
-3
@@ -365,8 +365,9 @@ newlines replaced by the string "\n". For example:
365
cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
366
```
367
368
-It is _not_ the path to a certificate file (and there is no "certfile"
369
-option).
368
+It is _not_ the path to a certificate file, though you can set a
369
+registry-scoped "certfile" path like
370
+"//other-registry.tld/:certfile=/path/to/cert.pem".
371
372
<!-- automatically generated, do not edit manually -->
373
<!-- see lib/utils/config/definitions.js -->
@@ -954,7 +955,8 @@ format with newlines replaced by the string "\n". For example:
955
key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
956
```
957
957
-It is _not_ the path to a key file (and there is no "keyfile" option).
958
+It is _not_ the path to a key file, though you can set a registry-scoped
959
+"keyfile" path like "//other-registry.tld/:keyfile=/path/to/key.pem".
960
961
<!-- automatically generated, do not edit manually -->
962
<!-- see lib/utils/config/definitions.js -->