CLI documentation update from CI

npm-cli-bot · npm-cli-bot · commit 55a684e5a790 · 2022-07-21T03:03:21.000Z
diff --git a/cli/v8 b/cli/v8
@@ -1 +1 @@
-Subproject commit 51b12a085e087609c99befccfd6a98ef8a9919d0
+Subproject commit 4c945302fc2aa6854dc014fe31d6f5dfa96f7b52
diff --git a/content/cli/v8/commands/npm-audit.md b/content/cli/v8/commands/npm-audit.md
@@ -53,14 +53,55 @@ output, it simply changes the command's failure threshold.
 
 ### Audit Signatures
 
-This command can also audit the integrity values of the packages in your
-tree against any signatures present in the registry they were downloaded
-from.  npm will attempt to download the keys from `/-/npm/v1/keys` on
-each the registry used to download any given package.  It will then
-check the `dist.signatures` object in the package itself, and verify the
-`sig` present there using the `keyid` there, matching it with a key
-returned from the registry.  The command for this is `npm audit
-signatures`
+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.
+
+Registry signatures can be verified using the following `audit` command:
+
+```bash
+$ npm audit signatures
+```
+
+The npm CLI supports registry signatures and signing keys provided by any registry if the following conventions are followed:
+
+1. Signatures are provided in the package's `packument` in each published version within the `dist` object:
+
+```json
+"dist":{
+  "..omitted..": "..omitted..",
+  "signatures": [{
+    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
+    "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
+  }]
+}
+```
+
+See this [example](https://registry.npmjs.org/light-cycle/1.4.3) of a signed package from the public npm registry.
+
+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.
+
+2. Public signing keys are provided at `registry-host.tld/-/npm/v1/keys` in the following format:
+
+```
+{
+  "keys": [{
+    "expires": null,
+    "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
+    "keytype": "ecdsa-sha2-nistp256",
+    "scheme": "ecdsa-sha2-nistp256",
+    "key": "{{B64_PUBLIC_KEY}}"
+  }]
+}
+```
+
+Keys response:
+
+- `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`
+- `keydid`: sha256 fingerprint of the public key
+- `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
+- `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
+- `key`: base64 encoded public key
+
+See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
 
 ### Audit Endpoints
 
diff --git a/content/cli/v8/configuring-npm/folders.md b/content/cli/v8/configuring-npm/folders.md
@@ -210,7 +210,7 @@ For a graphical breakdown of what is installed where, use `npm ls`.
 #### Publishing
 
 Upon publishing, npm will look in the `node_modules` folder.  If any of
-the items there are not in the `bundledDependencies` array, then they will
+the items there are not in the `bundleDependencies` array, then they will
 not be included in the package tarball.
 
 This allows a package maintainer to install all of their dependencies
diff --git a/content/cli/v8/configuring-npm/package-json.md b/content/cli/v8/configuring-npm/package-json.md
@@ -839,14 +839,14 @@ if the `soy-milk` package is not installed on the host. This allows you to
 integrate and interact with a variety of host packages without requiring
 all of them to be installed.
 
-### bundledDependencies
+### bundleDependencies
 
 This defines an array of package names that will be bundled when publishing
 the package.
 
 In cases where you need to preserve npm packages locally or have them
 available through a single file download, you can bundle the packages in a
-tarball file by specifying the package names in the `bundledDependencies`
+tarball file by specifying the package names in the `bundleDependencies`
 array and executing `npm pack`.
 
 For example:
@@ -857,7 +857,7 @@ If we define a package.json like this:
 {
   "name": "awesome-web-framework",
   "version": "1.0.0",
-  "bundledDependencies": [
+  "bundleDependencies": [
     "renderized",
     "super-streams"
   ]
@@ -870,9 +870,9 @@ can be installed in a new project by executing `npm install
 awesome-web-framework-1.0.0.tgz`.  Note that the package names do not
 include any versions, as that information is specified in `dependencies`.
 
-If this is spelled `"bundleDependencies"`, then that is also honored.
+If this is spelled `"bundledDependencies"`, then that is also honored.
 
-Alternatively, `"bundledDependencies"` can be defined as a boolean value. A
+Alternatively, `"bundleDependencies"` can be defined as a boolean value. A
 value of `true` will bundle all dependencies, a value of `false` will bundle
 none.
 
diff --git a/content/cli/v8/using-npm/config.md b/content/cli/v8/using-npm/config.md
@@ -365,8 +365,9 @@ newlines replaced by the string "\n". For example:
 cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
 ```
 
-It is _not_ the path to a certificate file (and there is no "certfile"
-option).
+It is _not_ the path to a certificate file, though you can set a
+registry-scoped "certfile" path like
+"//other-registry.tld/:certfile=/path/to/cert.pem".
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
@@ -954,7 +955,8 @@ format with newlines replaced by the string "\n". For example:
 key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
 ```
 
-It is _not_ the path to a key file (and there is no "keyfile" option).
+It is _not_ the path to a key file, though you can set a registry-scoped
+"keyfile" path like "//other-registry.tld/:keyfile=/path/to/key.pem".
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
