From a507829172d5ec75ec82364d6ffa946fe7d51b94 Mon Sep 17 00:00:00 2001 From: Nathan Fritz Date: Tue, 18 Oct 2022 15:22:39 -0700 Subject: [PATCH] feat: deprecated `key`, `cert` config options and updated registry scoped auth docs --- docs/lib/content/configuring-npm/npmrc.md | 9 +++ docs/lib/content/using-npm/registry.md | 3 + lib/utils/config/definitions.js | 14 +++++ tap-snapshots/test/lib/docs.js.test.cjs | 72 +++++++++++++---------- 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 d252f09b81a68..8cd532abc1c2d 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 5fab60ff4d49c..8d5ac94160b33 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 b8a7ec2d91de4..86ab9ed74d2ed 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 15ceed5c16d3a..a0651e34ec4e8 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