[dec 16th]: Doc Changes for 2FA Publishing and Secure By Default (#1790)
## Overview This is a PR to update the documentation to reflect the following changes coming to the npm registry 1. The default package setting for all newly created packages will be `Require two-factor authentication or a granular access token with bypass 2fa enabled` 1. Publishing a package will require the user to have 2fa enabled or use a granular access token with bypass 2fa enabled. ## Summary of file changes 📖 - Major updates to **Requiring 2FA for package publishing and settings modification** to highlight that 2FA or gat is required for publishing. Package settings options and image is updated. - Preview: https://npm-4360decefc-15913497.drafts.github.io/requiring-2fa-for-package-publishing-and-settings-modification - Adding notice to `npm publish` - Preview: https://npm-4360decefc-15913497.drafts.github.io/cli/v11/commands/npm-publish - Slight changes to `npm access` to remove option for no 2fa package setting. - Preview: https://npm-4360decefc-15913497.drafts.github.io/cli/v11/commands/npm-access - Adding a standardized notice to many pages (contributing packages, organizational settings, about 2 factor authentication) - Preview: https://npm-4360decefc-15913497.drafts.github.io/creating-node-js-modules - Adjusting the wording on **Using private packages in a CI/CD workflow** to `If trusted publishing is not available for your CI/CD provider, you must create a [granular access token with bypass 2FA enabled][create-token] on the website. This will allow you to publish in your CI/CD workflows even if you have two-factor authentication enabled on your account.` - Preview: https://npm-4360decefc-15913497.drafts.github.io/using-private-packages-in-a-ci-cd-workflow --------- Co-authored-by: Karen Li <47998177+karenjli@users.noreply.github.com> Co-authored-by: Nishant Gupta <nishantms@github.com>
sam crochet committed
Dec 10, 2025 at 10:23 UTC
b8298f9f1c98719e66cd3cf8c18fd1fcf04ff47a
12 files changed
+112
-44
content/cli/v11/commands/npm-access.mdx
+1
-1
@@ -42,7 +42,7 @@ npm access list packages [<user>|<scope>|<scope:team>] [<package>]
42
npm access list collaborators [<package> [<user>]]
43
npm access get status [<package>]
44
npm access set status=public|private [<package>]
45
-npm access set mfa=none|publish|automation [<package>]
45
+npm access set mfa=publish|automation [<package>]
46
npm access grant <read-only|read-write> <scope:team> [<package>]
47
npm access revoke <scope:team> [<package>]
48
```
content/cli/v11/commands/npm-publish.mdx
+11
@@ -49,6 +49,17 @@ Publishes a package to the registry so that it can be installed by name.
49
50
Publish the package in the current directory:
51
52
+<Note variant="warning">
53
+
54
+**Important:** Publishing to npm requires either:
55
+
56
+- Two-factor authentication (2FA) enabled on your account, OR
57
+- A granular access token with bypass 2FA enabled
58
+
59
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
60
+
61
+</Note>
62
+
63
```bash
64
npm publish
65
```
content/getting-started/setting-up-your-npm-user-account/about-two-factor-authentication.mdx
+11
@@ -20,6 +20,17 @@ When you enable 2FA, you will be prompted for a second form of authentication be
20
21
</Note>
22
23
+<Note variant="warning">
24
+
25
+**Important:** Publishing to npm requires either:
26
+
27
+- Two-factor authentication (2FA) enabled on your account, OR
28
+- A granular access token with bypass 2FA enabled
29
+
30
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
31
+
32
+</Note>
33
+
34
## Two-factor authentication on npm
35
36
Two-factor authentication on npm can be enabled for authorization and writes, or authorization only.
content/getting-started/setting-up-your-npm-user-account/configuring-two-factor-authentication.mdx
+12
-28
@@ -6,6 +6,17 @@ import shared from '~/shared.js'
6
7
You can enable two-factor authentication (2FA) on your npm user account to protect against unauthorized access to your account and packages using a [security-key][webauthn].
8
9
+<Note variant="warning">
10
+
11
+**Important:** Publishing to npm requires either:
12
+
13
+- Two-factor authentication (2FA) enabled on your account, OR
14
+- A granular access token with bypass 2FA enabled
15
+
16
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
17
+
18
+</Note>
19
+
20
## Prerequisites
21
22
Before you enable 2FA on your npm user account, you must:
@@ -54,34 +65,6 @@ For more information on supported 2FA methods, see "[About two-factor authentica
65
66
8. Click **Go back to settings** after confirming that you have saved your codes.
67
57
-### Disabling 2FA for writes
58
-
59
-Check the [Authorization and writes][authorization-and-writes] section for more information on different operations that requires 2FA when this mode is enabled.
60
-
61
-<Note>
62
-
63
-**Note**: As a recommended setting, 2FA for write operations are _automatically enabled_ when setting up 2FA. The following steps explain how to disable it.
64
-
65
-</Note>
66
-
67
-1. <>{shared['user-login'].text}</>
68
-
69
- <>{shared['user-login'].image}</>
70
-
71
-2. <>{shared['account-settings'].text}</>
72
-
73
- <>{shared['account-settings'].image}</>
74
-
75
-3. On the account settings page, under "Two-Factor Authentication", click **Modify 2FA**.
76
-
77
- <Screenshot src="/getting-started/setting-up-your-npm-user-account/2fa-modify.png" alt="Screenshot showing Modify 2FA button" />
78
-
79
-4. From the "Manage Two-Factor Authentication" navigate to "Additional Options" section
80
-
81
-5. Clear the checkbox for "Require two-factor authentication for write actions" and click "Update Preferences"
82
-
83
- <Screenshot src="/getting-started/setting-up-your-npm-user-account/disable-2fa-button.png" alt="Screenshot showing a cleared check box to disable 2fa under Addition options" />
84
-
68
### Disabling 2FA
69
70
If you have 2FA enabled, you can remove it from your account settings page.
@@ -193,6 +176,7 @@ The Twitter or GitHub account is now linked to your npm account. To remove the l
176
[can-i-use]: https://caniuse.com/#search=webauthn
177
[viewing-and-regenerating-recovery-code]: /recovering-your-2fa-enabled-account#viewing-and-regenerating-recovery-code
178
[webauthn]: https://webauthn.guide/
179
+[creating-token]: /creating-and-viewing-access-tokens
180
[u2f]: https://en.wikipedia.org/wiki/Universal_2nd_Factor
181
[windows-hello]: https://support.microsoft.com/en-us/windows/learn-about-windows-hello-and-set-it-up-dae28983-8242-bb2a-d3d1-87c9d265a5f0
182
[touch-id]: https://support.apple.com/en-gb/HT204587
content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx
+1
-1
@@ -45,7 +45,7 @@ For more information on creating granular access tokens, including CIDR-whitelis
45
46
For publishing packages in continuous deployment environments, we strongly recommend using [trusted publishing](/trusted-publishers) when available, as it provides enhanced security without requiring token management.
47
48
-If trusted publishing is not available for your CI/CD provider, you can create a [granular access token with bypass 2FA enabled][create-token] on the website. This will allow you to publish even if you have two-factor authentication enabled on your account.
48
+If trusted publishing is not available for your CI/CD provider, you must create a [granular access token with bypass 2FA enabled][create-token] on the website. This will allow you to publish in your CI/CD workflows even if you have two-factor authentication enabled on your account.
49
50
<Note>
51
content/organizations/creating-and-managing-organizations/requiring-two-factor-authentication-in-your-organization.mdx
+11
@@ -6,6 +6,17 @@ import shared from '~/shared.js'
6
7
Organization owners can require organization members to enable two-factor authentication for their personal accounts, making it harder for malicious actors to access an organization's packages and settings.
8
9
+<Note variant="warning">
10
+
11
+**Important:** Publishing to npm requires either:
12
+
13
+- Two-factor authentication (2FA) enabled on your account, OR
14
+- A granular access token with bypass 2FA enabled
15
+
16
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
17
+
18
+</Note>
19
+
20
## About two-factor authentication for organizations
21
22
Two-factor authentication (2FA) is an extra layer of security used when logging into websites or apps. You can require all members in your organization to enable two-factor authentication on npm. For more information about two-factor authentication, see ["Configuring two-factor authentication"][configure-2fa].
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-private-packages.mdx
+14
@@ -81,6 +81,17 @@ npm install my-package
81
82
By default, scoped packages are published with private visibility.
83
84
+<Note variant="warning">
85
+
86
+**Important:** Publishing to npm requires either:
87
+
88
+- Two-factor authentication (2FA) enabled on your account, OR
89
+- A granular access token with bypass 2FA enabled
90
+
91
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
92
+
93
+</Note>
94
+
95
1. On the command line, navigate to the root directory of your package.
96
97
```
@@ -109,3 +120,6 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
120
[cli-publish]: /cli/publish
121
[reg-config]: configuring-your-registry-settings-as-an-npm-enterprise-user#using-npmrc-to-manage-multiple-profiles-for-different-registries
122
[pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
123
+[config-2fa]: /configuring-two-factor-authentication
124
+[creating-token]: /creating-and-viewing-access-tokens
125
+[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-scoped-public-packages.mdx
+14
@@ -77,6 +77,17 @@ npm install /path/to/my-test-package
77
78
By default, scoped packages are published with private visibility. To publish a scoped package with public visibility, use `npm publish --access public`.
79
80
+<Note variant="warning">
81
+
82
+**Important:** Publishing to npm requires either:
83
+
84
+- Two-factor authentication (2FA) enabled on your account, OR
85
+- A granular access token with bypass 2FA enabled
86
+
87
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
88
+
89
+</Note>
90
+
91
1. On the command line, navigate to the root directory of your package.
92
93
```
@@ -111,3 +122,6 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
122
[cli-publish]: /cli/publish
123
[pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
124
[provenance-how-to]: /generating-provenance-statements
125
+[config-2fa]: /configuring-two-factor-authentication
126
+[creating-token]: /creating-and-viewing-access-tokens
127
+[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx
+14
@@ -58,6 +58,17 @@ npm install path/to/my-package
58
59
## Publishing unscoped public packages
60
61
+<Note variant="warning">
62
+
63
+**Important:** Publishing to npm requires either:
64
+
65
+- Two-factor authentication (2FA) enabled on your account, OR
66
+- A granular access token with bypass 2FA enabled
67
+
68
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
69
+
70
+</Note>
71
+
72
1. On the command line, navigate to the root directory of your package.
73
74
```
@@ -89,3 +100,6 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
100
[cli-publish]: /cli/publish
101
[pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
102
[provenance-how-to]: /generating-provenance-statements
103
+[config-2fa]: /configuring-two-factor-authentication
104
+[creating-token]: /creating-and-viewing-access-tokens
105
+[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
content/packages-and-modules/contributing-packages-to-the-registry/creating-node-js-modules.mdx
+16
-2
@@ -36,8 +36,20 @@ exports.printMsg = function() {
36
## Test your module
37
38
1. Publish your package to npm:
39
- - For [private packages][priv-pkg-pub] and [unscoped packages][unscoped-pkg-pub], use `npm publish`.
40
- - For [scoped public packages][scoped-pkg-pub], use `npm publish --access public`
39
+
40
+<Note variant="warning">
41
+
42
+**Important:** Publishing to npm requires either:
43
+
44
+- Two-factor authentication (2FA) enabled on your account, OR
45
+- A granular access token with bypass 2FA enabled
46
+
47
+For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
48
+
49
+</Note>
50
+
51
+- For [private packages][priv-pkg-pub] and [unscoped packages][unscoped-pkg-pub], use `npm publish`.
52
+- For [scoped public packages][scoped-pkg-pub], use `npm publish --access public`
53
54
2. On the command line, create a new test directory outside of your project directory.
55
@@ -73,3 +85,5 @@ exports.printMsg = function() {
85
[priv-pkg-pub]: creating-and-publishing-private-packages#publishing-private-packages
86
[unscoped-pkg-pub]: creating-and-publishing-unscoped-public-packages#publishing-unscoped-public-packages
87
[scoped-pkg-pub]: creating-and-publishing-scoped-public-packages#publishing-scoped-public-packages
88
+[config-2fa]: /configuring-two-factor-authentication
89
+[creating-token]: /creating-and-viewing-access-tokens
content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx
+7
-12
@@ -4,9 +4,9 @@ title: Requiring 2FA for package publishing and settings modification
4
5
import shared from '~/shared.js'
6
7
-To protect your packages, as a package publisher, you can require everyone who has write access to a package to have two-factor authentication (2FA) enabled. This will require that users provide 2FA credentials in addition to their login token when they publish the package. For more information, see "[Configuring two-factor authentication][config-2fa]".
7
+All packages now require two-factor authentication (2FA) or a [granular access tokens with bypass 2FA enabled][creating-granular-access-token] for creating and publishing packages.
8
9
-You may also choose to allow publishing with either two-factor authentication _or_ with [granular access tokens with bypass 2FA enabled][creating-granular-access-token]. This lets you configure tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes.
9
+Modifying a package's settings also requires two-factor authentication (2FA).
10
11
For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), which provides secure, token-free publishing that automatically enforces strong authentication without requiring manual token management.
12
@@ -21,7 +21,7 @@ For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), w
21
22
</Note>
23
24
-## Configuring two-factor authentication
24
+## Configuring two-factor authentication on package settings
25
26
1. <>{shared['user-login'].text}</>
27
@@ -34,18 +34,13 @@ For CI/CD workflows, consider using [trusted publishing](/trusted-publishers), w
34
<Screenshot src="/packages-and-modules/securing-your-code/2fa-package-admin.png" alt="Screenshot showing the admin tab on a package page" />
35
36
4. Under "Publishing access", select the requirements to publish a package.
37
- 1. **Dont require two-factor authentication**
38
- With this option, a maintainer can publish a package or change the package settings whether they have two-factor authentication enabled or not. This is the least secure setting.
39
-
40
- 2. **Require two-factor authentication or granular access tokens**
41
- With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to enter 2FA credentials when they perform the publish. However, maintainers may also create a [granular access token with bypass 2FA enabled][creating-granular-access-token] and use that to publish. A second factor is _not_ required when using these specific token types, making them useful for continuous integration and continuous deployment workflows.
42
-
43
- 3. **Require two-factor authentication and disallow tokens**
44
- With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to enter 2FA credentials when they perform the publish. Granular access tokens cannot be used to publish packages, regardless of their bypass 2FA setting.
37
+ 1. **Require two-factor authentication or a granular access token with bypass 2fa enabled** (Default)
38
+ This is the default option for all new packages. With this option, maintainers must have two-factor authentication enabled for their account. If they publish a package interactively, using the `npm publish` command, they will be required to respond to a 2FA prompt when they perform the publish. However, maintainers may also create a [granular access token with bypass 2FA enabled][creating-granular-access-token] and use that for a non-interactive publish.
39
+ 2. **Require two-factor authentication and disallow tokens** (Recommended) With this option, a maintainer must have two-factor authentication enabled for their account, and they must publish interactively. Maintainers will be required to respond to a 2FA prompt when they perform the publish. Granular access tokens cannot be used to publish packages, regardless of their bypass 2FA setting.
40
41
<Screenshot src="/packages-and-modules/securing-your-code/2fa-package-setting.png" alt="Screenshot showing the require two-factor option for a package" />
42
48
-5. Click **Update Package Settings**.
43
+5 . Click **Update Package Settings**.
44
45
[config-2fa]: configuring-two-factor-authentication
46
[creating-granular-access-token]: creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website
static/packages-and-modules/securing-your-code/2fa-package-setting.png
Binary files a/static/packages-and-modules/securing-your-code/2fa-package-setting.png and b/static/packages-and-modules/securing-your-code/2fa-package-setting.png differ