docs: npm-access through npm-dedupe

The big one here is npm-audit, since that changed so significantly in
npm v7.  The others are mostly small copyedits and improvements to the
consistency of ordering sections.

docs/content/cli-commands/npm-access.md

@@ -75,11 +75,12 @@ You must have privileges to set the access of a package:
 * You have been given read-write privileges for a package, either as a member
   of a team or directly as an owner.
 
-If you have two-factor authentication enabled then you'll have to pass in an
-otp with `--otp` when making access changes.
+If you have two-factor authentication enabled then you'll be prompted to
+provide an otp token, or may use the `--otp=...` option to specify it on
+the command line.
 
-If your account is not paid, then attempts to publish scoped packages will fail
-with an HTTP 402 status code (logically enough), unless you use
+If your account is not paid, then attempts to publish scoped packages will
+fail with an HTTP 402 status code (logically enough), unless you use
 `--access=public`.
 
 Management of teams and team memberships is done with the `npm team` command.

docs/content/cli-commands/npm-adduser.md

@@ -54,8 +54,8 @@ with the specified scope. See [`scope`](/using-npm/scope). You can use both at t
 e.g.
 
 ```bash
-    npm adduser --registry=http://myregistry.example.com --scope=@myco
-```    
+npm adduser --registry=http://myregistry.example.com --scope=@myco
+```
 
 This will set a registry for the given scope and login or create a user for
 that registry at the same time.
@@ -69,7 +69,7 @@ registry should include authorization information. Useful for private
 registries. Can be used with `--registry` and / or `--scope`, e.g.
 
 ```bash
-    npm adduser --registry=http://private-registry.example.com --always-auth
+npm adduser --registry=http://private-registry.example.com --always-auth
 ```
 
 This will ensure that all requests to that registry (including for tarballs)

docs/content/cli-commands/npm-audit.md

@@ -17,118 +17,180 @@ npm audit fix [--force|--package-lock-only|--dry-run]
 common options: [--production] [--only=(dev|prod)]
 ```
 
+### Description
+
+The audit command submits a description of the dependencies configured in
+your project to your default registry and asks for a report of known
+vulnerabilities.  If any vulnerabilities are found, then the impact and
+appropriate remediation will be calculated.  If the `fix` argument is
+provided, then remediations will be applied to the package tree.
+
+The command will exit with a 0 exit code if no vulnerabilities were found.
+
+Note that some vulnerabilities cannot be fixed automatically and will
+require manual intervention or review.  Also note that since `npm audit
+fix` runs a full-fledged `npm install` under the hood, all configs that
+apply to the installer will also apply to `npm install` -- so things like
+`npm audit fix --package-lock-only` will work as expected.
+
+By default, the audit command will exit with a non-zero code if any
+vulnerability is found. It may be useful in CI environments to include the
+`--audit-level` parameter to specify the minimum vulnerability level that
+will cause the command to fail. This option does not filter the report
+output, it simply changes the command's failure threshold.
+
+### Audit Endpoints
+
+There are two audit endpoints that npm may use to fetch vulnerability
+information: the `Bulk Advisory` endpoint and the `Quick Audit` endpoint.
+
+#### Bulk Advisory Endpoint
+
+As of version 7, npm uses the much faster `Bulk Advisory` endpoint to
+optimize the speed of calculating audit results.
+
+npm will generate a JSON payload with the name and list of versions of each
+package in the tree, and POST it to the default configured registry at
+the path `/-/npm/v1/security/advisories/bulk`.
+
+Any packages in the tree that do not have a `version` field in their
+package.json file will be ignored.  If any `--omit` options are specified
+(either via the `--omit` config, or one of the shorthands such as
+`--production`, `--only=dev`, and so on), then packages will be omitted
+from the submitted payload as appropriate.
+
+If the registry responds with an error, or with an invalid response, then
+npm will attempt to load advisory data from the `Quick Audit` endpoint.
+
+The expected result will contain a set of advisory objects for each
+dependency that matches the advisory range.  Each advisory object contains
+a `name`, `url`, `id`, `severity`, `vulnerable_versions`, and `title`.
+
+npm then uses these advisory objects to calculate vulnerabilities and
+meta-vulnerabilities of the dependencies within the tree.
+
+#### Quick Audit Endpoint
+
+If the `Bulk Advisory` endpoint returns an error, or invalid data, npm will
+attempt to load advisory data from the `Quick Audit` endpoint, which is
+considerably slower in most cases.
+
+The full package tree as found in `package-lock.json` is submitted, along
+with the following pieces of additional metadata:
+
+* `npm_version`
+* `node_version`
+* `platform`
+* `arch`
+* `node_env`
+
+All packages in the tree are submitted to the Quick Audit endpoint.
+Omitted dependency types are skipped when generating the report.
+
+#### Scrubbing
+
+Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
+packages from the submitted report if their name contained a `/` character,
+so as to avoid leaking the names of potentially private packages or git
+URLs.
+
+However, in practice, this resulted in audits often failing to properly
+detect meta-vulnerabilities, because the tree would appear to be invalid
+due to missing dependencies, and prevented the detection of vulnerabilities
+in package trees that used git dependencies or private modules.
+
+This scrubbing has been removed from npm as of version 7.
+
+#### Calculating Meta-Vulnerabilities and Remediations
+
+npm uses the
+[`@npmcli/metavuln-calculator`](http://npm.im/@npmcli/metavuln-calculator)
+module to turn a set of security advisories into a set of "vulnerability"
+objects.  A "meta-vulnerability" is a dependency that is vulnerable by
+virtue of dependence on vulnerable versions of a vulnerable package.
+
+For example, if the package `foo` is vulnerable in the range `>=1.0.2
+<2.0.0`, and the package `bar` depends on `foo@^1.1.0`, then that version
+of `bar` can only be installed by installing a vulnerable version of `foo`.
+In this case, `bar` is a "metavulnerability".
+
+Once metavulnerabilities for a given package are calculated, they are
+cached in the `~/.npm` folder and only re-evaluated if the advisory range
+changes, or a new version of the package is published (in which case, the
+new version is checked for metavulnerable status as well).
+
+If the chain of metavulnerabilities extends all the way to the root
+project, and it cannot be updated without changing its dependency ranges,
+then `npm audit fix` will require the `--force` option to apply the
+remediation.  If remediations do not require changes to the dependency
+ranges, then all vulnerable packages will be updated to a version that does
+not have an advisory or metavulnerability posted against it.
+
+### Exit Code
+
+The `npm audit` command will exit with a 0 exit code if no vulnerabilities
+were found.  The `npm audit fix` command will exit with 0 exit code if no
+vulnerabilities are found _or_ if the remediation is able to successfully
+fix all vulnerabilities.
+
+If vulnerabilities were found the exit code will depend on the
+`audit-level` configuration setting.
+
 ### Examples
 
 Scan your project for vulnerabilities and automatically install any compatible
 updates to vulnerable dependencies:
+
 ```bash
 $ npm audit fix
 ```
 
 Run `audit fix` without modifying `node_modules`, but still updating the
 pkglock:
+
 ```bash
 $ npm audit fix --package-lock-only
 ```
 
 Skip updating `devDependencies`:
+
 ```bash
 $ npm audit fix --only=prod
 ```
 
-Have `audit fix` install semver-major updates to toplevel dependencies, not just
-semver-compatible ones:
+Have `audit fix` install SemVer-major updates to toplevel dependencies, not
+just SemVer-compatible ones:
+
 ```bash
 $ npm audit fix --force
 ```
 
 Do a dry run to get an idea of what `audit fix` will do, and _also_ output
 install information in JSON format:
+
 ```bash
 $ npm audit fix --dry-run --json
 ```
 
-Scan your project for vulnerabilities and just show the details, without fixing
-anything:
+Scan your project for vulnerabilities and just show the details, without
+fixing anything:
+
 ```bash
 $ npm audit
 ```
 
 Get the detailed audit report in JSON format:
-```bash
-$ npm audit --json
-```
-
-Get the detailed audit report in plain text result, separated by tab characters, allowing for
-future reuse in scripting or command line post processing, like for example, selecting
-some of the columns printed:
-```bash
-$ npm audit --parseable
-```
 
-To parse columns, you can use for example `awk`, and just print some of them:
 ```bash
-$ npm audit --parseable | awk -F $'\t' '{print $1,$4}'
+$ npm audit --json
 ```
 
 Fail an audit only if the results include a vulnerability with a level of moderate or higher:
+
 ```bash
 $ npm audit --audit-level=moderate
 ```
 
-### Description
-
-The audit command submits a description of the dependencies configured in
-your project to your default registry and asks for a report of known
-vulnerabilities. The report returned includes instructions on how to act on
-this information. The command will exit with a 0 exit code if no
-vulnerabilities were found.
-
-You can also have npm automatically fix the vulnerabilities by running `npm
-audit fix`. Note that some vulnerabilities cannot be fixed automatically and
-will require manual intervention or review. Also note that since `npm audit fix`
-runs a full-fledged `npm install` under the hood, all configs that apply to the
-installer will also apply to `npm install` -- so things like `npm audit fix
---package-lock-only` will work as expected.
-
-By default, the audit command will exit with a non-zero code if any vulnerability
-is found. It may be useful in CI environments to include the `--audit-level` parameter
-to specify the minimum vulnerability level that will cause the command to fail. This
-option does not filter the report output, it simply changes the command's failure
-threshold.
-
-### Content Submitted
-
-* npm_version
-* node_version
-* platform
-* node_env
-* A scrubbed version of your package-lock.json or npm-shrinkwrap.json
-
-#### Scrubbing
-
-In order to ensure that potentially sensitive information is not included in
-the audit data bundle, some dependencies may have their names (and sometimes
-versions) replaced with opaque non-reversible identifiers.  It is done for
-the following dependency types:
-
-* Any module referencing a scope that is configured for a non-default
-  registry has its name scrubbed.  (That is, a scope you did a `npm login --scope=@ourscope` for.)
-* All git dependencies have their names and specifiers scrubbed.
-* All remote tarball dependencies have their names and specifiers scrubbed.
-* All local directory and tarball dependencies have their names and specifiers scrubbed.
-
-The non-reversible identifiers are a sha256 of a session-specific UUID and the
-value being replaced, ensuring a consistent value within the payload that is
-different between runs.
-
-### Exit Code
-
-The `npm audit` command will exit with a 0 exit code if no vulnerabilities were found.
-
-If vulnerabilities were found the exit code will depend on the `audit-level`
-configuration setting.
-
 ### See Also
 
 * [npm install](/cli-commands/install)

docs/content/cli-commands/npm-bin.md

@@ -9,6 +9,7 @@ description: Display npm bin folder
 ## Display npm bin folder
 
 ### Synopsis
+
 ```bash
 npm bin [-g|--global]
 ```

docs/content/cli-commands/npm-bugs.md

@@ -6,9 +6,10 @@ description: Bugs for a package in a web browser maybe
 
 # npm-bugs(1)
 
-## Bugs for a package in a web browser maybe
+## Report bugs for a package in a web browser
 
 ### Synopsis
+
 ```bash
 npm bugs [<pkgname> [<pkgname> ...]]
 
@@ -17,10 +18,10 @@ aliases: issues
 
 ### Description
 
-This command tries to guess at the likely location of a package's
-bug tracker URL, and then tries to open it using the `--browser`
-config param. If no package name is provided, it will search for
-a `package.json` in the current folder and use the `name` property.
+This command tries to guess at the likely location of a package's bug
+tracker URL, and then tries to open it using the `--browser` config param.
+If no package name is provided, it will search for a `package.json` in the
+current folder and use the `name` property.
 
 ### Configuration
 
@@ -43,7 +44,6 @@ Set to `true` to use default system URL opener.
 
 The base URL of the npm package registry.
 
-
 ### See Also
 
 * [npm docs](/cli-commands/docs)

docs/content/cli-commands/npm-bundle.md

@@ -11,8 +11,8 @@ description: REMOVED
 ### Description
 
 The `npm bundle` command has been removed in 1.0, for the simple reason
-that it is no longer necessary, as the default behavior is now to
-install packages into the local space.
+that it is no longer necessary, as the default behavior is now to install
+packages into the local space.
 
 Just use `npm install` now to do what `npm bundle` used to do.