feat: deprecated `key`, `cert` config options and updated registry scoped auth docs

4 files changed, 66 insertions, 32 deletions

diff --git a/docs/lib/content/configuring-npm/npmrc.md b/docs/lib/content/configuring-npm/npmrc.md
index d252f09b8..8cd532abc 100644
--- a/docs/lib/content/configuring-npm/npmrc.md
+++ b/docs/lib/content/configuring-npm/npmrc.md
@@ -97,6 +97,15 @@ The settings `_auth`, `_authToken`, `username` and `_password` must all be
 scoped to a specific registry. This ensures that `npm` will never send
 credentials to the wrong host.
 
+The full list is:
+ - `_auth` (base64 authentication string)
+ - `_authToken` (authentication token)
+ - `username`
+ - `_password`
+ - `email`
+ - `certfile` (path to certificate file)
+ - `keyfile` (path to key file)
+
 In order to scope these values, they must be prefixed by a URI fragment.
 If the credential is meant for any request to a registry on a single host,
 the scope may look like `//registry.npmjs.org/:`. If it must be scoped to a
diff --git a/docs/lib/content/using-npm/registry.md b/docs/lib/content/using-npm/registry.md
index 5fab60ff4..8d5ac9416 100644
--- a/docs/lib/content/using-npm/registry.md
+++ b/docs/lib/content/using-npm/registry.md
@@ -31,6 +31,9 @@ used, which is supplied by the [`registry` config](/using-npm/config#registry)
 parameter.  See [`npm config`](/commands/npm-config),
 [`npmrc`](/configuring-npm/npmrc), and [`config`](/using-npm/config) for more on
 managing npm's configuration.
+Authentication configuration such as auth tokens and certificates are configured
+specifically scoped to an individual registry. See
+[Auth Related Configuration](/configuring-npm/npmrc#auth-related-configuration)
 
 When the default registry is used in a package-lock or shrinkwrap is has the
 special meaning of "the currently configured registry". If you create a lock
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index b8a7ec2d9..86ab9ed74 100644
--- a/lib/utils/config/definitions.js
+++ b/lib/utils/config/definitions.js
@@ -422,6 +422,13 @@ define('cert', {
     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".
   `,
+  deprecated: `
+    \`key\` and \`cert\` are no longer used for most registry operations.
+    Use registry scoped \`keyfile\` and \`certfile\` instead.
+    Example:
+    //other-registry.tld/:keyfile=/path/to/key.pem
+    //other-registry.tld/:certfile=/path/to/cert.crt
+  `,
   flatten,
 })
 
@@ -1124,6 +1131,13 @@ define('key', {
     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".
   `,
+  deprecated: `
+    \`key\` and \`cert\` are no longer used for most registry operations.
+    Use registry scoped \`keyfile\` and \`certfile\` instead.
+    Example:
+    //other-registry.tld/:keyfile=/path/to/key.pem
+    //other-registry.tld/:certfile=/path/to/cert.crt
+  `,
   flatten,
 })
 
diff --git a/tap-snapshots/test/lib/docs.js.test.cjs b/tap-snapshots/test/lib/docs.js.test.cjs
index 15ceed5c1..a0651e34e 100644
--- a/tap-snapshots/test/lib/docs.js.test.cjs
+++ b/tap-snapshots/test/lib/docs.js.test.cjs
@@ -750,23 +750,6 @@ npm exec --package yo --package generator-node --call "yo node"
 \`\`\`
 
 
-#### \`cert\`
-
-* Default: null
-* Type: null or String
-
-A client certificate to pass when accessing the registry. Values should be
-in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with
-newlines replaced by the string "\\n". For example:
-
-\`\`\`ini
-cert="-----BEGIN CERTIFICATE-----\\nXXXX\\nXXXX\\n-----END CERTIFICATE-----"
-\`\`\`
-
-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".
-
 #### \`ci-name\`
 
 * Default: The name of the current CI system, or \`null\` when not on a known CI
@@ -1200,21 +1183,6 @@ Whether or not to output JSON data, rather than the normal output.
 
 Not supported by all npm commands.
 
-#### \`key\`
-
-* Default: null
-* Type: null or String
-
-A client key to pass when accessing the registry. Values should be in PEM
-format with newlines replaced by the string "\\n". For example:
-
-\`\`\`ini
-key="-----BEGIN PRIVATE KEY-----\\nXXXX\\nXXXX\\n-----END PRIVATE KEY-----"
-\`\`\`
-
-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".
-
 #### \`legacy-peer-deps\`
 
 * Default: false
@@ -1975,6 +1943,27 @@ When set to \`dev\` or \`development\`, this is an alias for \`--include=dev\`.
 
 \`--cache-min=9999 (or bigger)\` is an alias for \`--prefer-offline\`.
 
+#### \`cert\`
+
+* Default: null
+* Type: null or String
+* DEPRECATED: \`key\` and \`cert\` are no longer used for most registry
+  operations. Use registry scoped \`keyfile\` and \`certfile\` instead. Example:
+  //other-registry.tld/:keyfile=/path/to/key.pem
+  //other-registry.tld/:certfile=/path/to/cert.crt
+
+A client certificate to pass when accessing the registry. Values should be
+in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with
+newlines replaced by the string "\\n". For example:
+
+\`\`\`ini
+cert="-----BEGIN CERTIFICATE-----\\nXXXX\\nXXXX\\n-----END CERTIFICATE-----"
+\`\`\`
+
+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".
+
 #### \`dev\`
 
 * Default: false
@@ -2041,6 +2030,25 @@ Alias for \`--init-module\`
 
 Alias for \`--init-version\`
 
+#### \`key\`
+
+* Default: null
+* Type: null or String
+* DEPRECATED: \`key\` and \`cert\` are no longer used for most registry
+  operations. Use registry scoped \`keyfile\` and \`certfile\` instead. Example:
+  //other-registry.tld/:keyfile=/path/to/key.pem
+  //other-registry.tld/:certfile=/path/to/cert.crt
+
+A client key to pass when accessing the registry. Values should be in PEM
+format with newlines replaced by the string "\\n". For example:
+
+\`\`\`ini
+key="-----BEGIN PRIVATE KEY-----\\nXXXX\\nXXXX\\n-----END PRIVATE KEY-----"
+\`\`\`
+
+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".
+
 #### \`legacy-bundling\`
 
 * Default: false