Add docs for trusted publishing

Author: leobalter

content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx

@@ -12,7 +12,7 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc
 
 <Note>
 
-**Note:** For greater security, we recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) instead of legacy read-only tokens or legacy automation tokens.
+**Note:** For greater security, we recommend using [granular access tokens](#creating-granular-access-tokens-on-the-website) instead of legacy read-only tokens or legacy automation tokens. For CI/CD workflows, consider using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers), which eliminates the need for long-lived tokens entirely.
 
 </Note>
 
@@ -29,7 +29,7 @@ You can [create](#creating-access-tokens) and [view](#viewing-access-tokens) acc
 4. Select the type of access token:
    - **Read-only**: A read-only token can only be used to download packages from the registry. It will have permission to read any private package that you have access to. This is recommended for automation and workflows where you are installing packages, but not publishing new ones.
 
-   - **Automation**: An automation token can download packages and publish new ones, but if you have two-factor authentication (2FA) configured on your account, it will **not** be enforced. You can use an automation token in continuous integration workflows and other automation systems to publish a package even when you cannot enter a one-time passcode.
+   - **Automation**: An automation token can download packages and publish new ones, but if you have two-factor authentication (2FA) configured on your account, it will **not** be enforced. You can use an automation token in continuous integration workflows and other automation systems to publish a package even when you cannot enter a one-time passcode. For enhanced security in CI/CD workflows, consider using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers) instead, which eliminates the need for long-lived tokens.
 
    - **Publish**: A publish token can perform any action on your behalf, including downloading packages, publishing packages, and changing user settings or package settings. If you have two-factor authentication configured on your account, you will be required to enter a one-time passcode when using a publish token. This is recommended for interactive workflows such as a CLI.
 

content/integrations/integrating-npm-with-external-services/using-private-packages-in-a-ci-cd-workflow.mdx

@@ -6,6 +6,17 @@ redirect_from:
 
 You can use access tokens to test private npm packages with continuous integration (CI) systems, or deploy them using continuous deployment (CD) systems.
 
+## Recommended: Use trusted publishing for package publishing
+
+For publishing packages from CI/CD workflows, we recommend using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers) instead of access tokens. Trusted publishing uses OpenID Connect (OIDC) to provide secure, token-free publishing that eliminates the security risks associated with long-lived tokens.
+
+Trusted publishing is supported for:
+
+- [GitHub Actions](https://github.com/features/actions) (GitHub-hosted runners)
+- [GitLab CI/CD](https://docs.gitlab.com/ci/pipelines/) (GitLab.com shared runners)
+
+If you use a different CI/CD provider, or if you need to install private packages (not publish), you can use access tokens as described below.
+
 ## Create a new access token
 
 Create a new access token that will be used only to access npm packages from a CI/CD server.
@@ -24,7 +35,9 @@ For more information on creating access tokens, including CIDR-whitelisted token
 
 ### Continuous deployment
 
-Since continuous deployment environments usually involve the creation of a deploy artifact, you may wish to create an [automation token][create-token] on the website. This will allow you to publish even if you have two-factor authentication enabled on your account.
+For publishing packages in continuous deployment environments, we strongly recommend using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers) when available, as it provides enhanced security without requiring token management.
+
+If trusted publishing is not available for your CI/CD provider, you may create an [automation token][create-token] on the website. This will allow you to publish even if you have two-factor authentication enabled on your account.
 
 ### Interactive workflows
 

content/nav.yml

@@ -156,6 +156,8 @@
           url: /auditing-package-dependencies-for-security-vulnerabilities
         - title: Generating provenance statements
           url: /generating-provenance-statements
+        - title: Trusted publishing with OIDC
+          url: /trusted-publishers
         - title: About ECDSA registry signatures
           url: /about-registry-signatures
         - title: Verifying ECDSA registry signatures

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx

@@ -72,7 +72,7 @@ npm install path/to/my-package
 
    <Note>
 
-   **Note:** If you use GitHub Actions to publish your packages, you can generate provenance information for each package you publish. For more information, see "[Generating provenance statements][provenance-how-to]."
+   **Note:** If you use GitHub Actions or GitLab CI/CD to publish your packages, consider using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers) for enhanced security. Trusted publishing automatically generates provenance information and eliminates the need for access tokens in your CI/CD workflows. For more information, see "[Generating provenance statements][provenance-how-to]."
 
    </Note>
 

content/packages-and-modules/securing-your-code/generating-provenance-statements.mdx

@@ -42,6 +42,8 @@ Before you can publish your packages with provenance, you must:
   - GitHub Actions. For more information, see "[Publishing packages with provenance via GitHub Actions][github-provenance]."
   - GitLab CI/CD. For more information, see "[Publishing packages with provenance via GitLab CI/CD][gitlab-provenance]."
 
+**Note:** If you use [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers), provenance attestations are automatically generated for your packages without requiring the `--provenance` flag. This provides enhanced security and eliminates the need for access tokens in your CI/CD workflows.
+
 ## Publishing packages with provenance via GitHub Actions
 
 In order to establish provenance, you must use a supported cloud CI/CD provider and a cloud-hosted runner to publish your packages. GitHub Actions is a supported CI/CD platform that allows you to automate software development tasks. For more information, see [GitHub Actions][github-actions] in the GitHub documentation.

content/packages-and-modules/securing-your-code/requiring-2fa-for-package-publishing-and-settings-modification.mdx

@@ -8,6 +8,8 @@ To protect your packages, as a package publisher, you can require everyone who h
 
 You may also choose to allow publishing with either two-factor authentication _or_ with [automation tokens][creating-automation-token]. This lets you configure automation tokens in a CI/CD workflow, but requires two-factor authentication from interactive publishes.
 
+For CI/CD workflows, consider using [trusted publishing](/packages-and-modules/securing-your-code/trusted-publishers), which provides secure, token-free publishing that automatically enforces strong authentication without requiring manual token management.
+
 ## Configuring two-factor authentication
 
 1. <>{shared['user-login'].text}</>

content/packages-and-modules/securing-your-code/trusted-publishers.mdx

@@ -0,0 +1,269 @@
+---
+title: Trusted publishing for npm packages
+---
+
+Trusted publishing allows you to publish npm packages directly from your CI/CD workflows using [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) authentication, eliminating the need for long-lived npm tokens. This feature implements the [Trusted Publishers standard](https://repos.openssf.org/trusted-publishers-for-all-package-repositories) from the Open Source Security Foundation (OpenSSF), joining a growing ecosystem including [PyPI](https://docs.pypi.org/trusted-publishers/), [RubyGems](https://guides.rubygems.org/trusted-publishing/), and other major package registries in offering this security enhancement.
+
+<Note>
+
+**Note:** Trusted publishing requires [npm CLI](https://docs.npmjs.com/cli/v11) version 11.5.0 or later.
+
+</Note>
+
+## How trusted publishing works
+
+Trusted publishing creates a trust relationship between npm and your CI/CD provider using OIDC. When you configure a trusted publisher for your package, npm will accept publishes from the specific workflow you've authorized, in addition to traditional authentication methods like npm tokens and manual publishes. The npm CLI automatically detects OIDC environments and uses them for authentication before falling back to traditional tokens.
+
+This approach eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation. Instead, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.
+
+## Supported CI/CD providers
+
+Trusted publishing currently supports:
+
+- [GitHub Actions](https://github.com/features/actions) (GitHub-hosted runners)
+- [GitLab CI/CD Pipelines](https://docs.gitlab.com/ci/pipelines/) (GitLab.com shared runners)
+
+Self-hosted runners are not currently supported but are planned for future releases.
+
+## Configuring trusted publishing
+
+### Step 1: Add a trusted publisher on npmjs.com
+
+Navigate to your package settings on [npmjs.com](https://www.npmjs.com) and find the "**Trusted Publisher**" section. Under "**Select your publisher**", choose your CI/CD provider by clicking either the GitHub Actions or GitLab CI/CD button.
+
+<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher.png" alt="Screenshot showing the Trusted Publisher section with Select your publisher label and provider buttons" />
+
+#### For GitHub Actions
+
+Configure the following fields:
+
+- **Organization or user** (required): Your GitHub username or organization name
+- **Repository** (required): Your repository name
+- **Workflow filename** (required): The filename of your workflow (e.g., `publish.yml`)
+  - Enter only the filename, not the full path
+  - Must include the `.yml` or `.yaml` extension
+  - The workflow file must exist in `.github/workflows/` in your repository
+- **Environment name** (optional): If using [GitHub environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) for deployment protection
+
+<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-github-actions.png" alt="Screenshot of GitHub Actions trusted publisher configuration form" />
+
+#### For GitLab CI/CD
+
+Configure the following fields:
+
+- **Namespace** (required): Your GitLab username or group name
+- **Project name** (required): Your project name
+- **Top-level CI file path** (required): The path to your CI file (e.g., `.gitlab-ci.yml`)
+  - Must include the `.yml` extension
+- **Environment name** (optional): If using [GitLab environments](https://docs.gitlab.com/ee/ci/environments/)
+
+<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-gitlab.png" alt="Screenshot of GitLab CI/CD trusted publisher configuration form" />
+
+<Note>
+
+**Note:** Each package can only have one trusted publisher configured at a time.
+
+</Note>
+
+### Step 2: Configure your CI/CD workflow
+
+#### GitHub Actions configuration
+
+Add the required OIDC permissions to your workflow. Here's a complete example:
+
+```yaml
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      # Ensure npm 11.5.0 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - run: npm publish
+```
+
+The critical requirement is the `id-token: write` permission, which allows GitHub Actions to generate OIDC tokens. Learn more in [GitHub's OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
+
+#### GitLab CI/CD configuration
+
+Configure the OIDC ID token in your pipeline:
+
+```yaml
+stages:
+  - test
+  - build
+  - publish
+
+variables:
+  NODE_VERSION: '20'
+
+id_tokens:
+  NPM_ID_TOKEN:
+    aud: "npm:registry.npmjs.org"
+
+test:
+  stage: test
+  image: node:${NODE_VERSION}
+  script:
+    - npm ci
+    - npm test
+
+publish:
+  stage: publish
+  image: node:${NODE_VERSION}
+  script:
+    # Ensure npm 11.5.0 or later is installed
+    - npm install -g npm@latest
+    - npm ci
+    - npm run build --if-present
+    - npm publish
+  only:
+    - tags
+```
+
+The `id_tokens` configuration tells GitLab to generate an OIDC token for npm. Learn more in [GitLab's OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/).
+
+### Managing trusted publisher configurations
+
+You can modify or remove your trusted publisher configuration at any time through your package settings on [npmjs.com](https://npmjs.com). Each package can only have one trusted publisher connection at a time, but this connection can be edited or deleted as needed. To change providers (for example, switching from GitHub Actions to GitLab CI/CD), simply edit your existing configuration and select the new provider. The change takes effect immediately for future publishes. To remove trusted publishing entirely and return to token-based authentication, delete the trusted publisher configuration from your package settings.
+
+## Automatic provenance generation
+
+When you publish using trusted publishing, npm automatically generates and publishes [provenance attestations](./generating-provenance-statements) for your package. This happens by default—you don't need to add the `--provenance` flag to your publish command.
+
+<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-provenance.png" alt="Screenshot showing provenance badge/information on a package page" />
+
+Provenance provides cryptographic proof of where and how your package was built, allowing users to verify its authenticity. This automatic generation only applies when all of these conditions are met:
+
+- Publishing via trusted publishing (OIDC)
+- Publishing from a public repository
+- Publishing a public package
+
+<Note>
+
+**Note:** Provenance generation is [not supported for private repositories](https://github.blog/changelog/2023-07-25-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/), even when publishing public packages.
+
+</Note>
+
+### Disabling provenance generation
+
+While we strongly recommend keeping provenance enabled, you can disable it if needed. Set the `provenance` option to `false` in any of these ways:
+
+**Using environment variable:**
+
+```bash
+NPM_CONFIG_PROVENANCE=false npm publish
+```
+
+**In your `.npmrc` file:**
+
+```ini
+provenance=false
+```
+
+**In your `package.json`:**
+
+```json
+{
+  "publishConfig": {
+    "provenance": false
+  }
+}
+```
+
+## Security best practices
+
+### Prefer trusted publishing over tokens
+
+When trusted publishing is available for your workflow, always prefer it over long-lived tokens. Traditional npm tokens pose several security risks:
+
+- They can be accidentally exposed in CI logs or configuration files
+- They require manual rotation and management
+- If compromised, they provide persistent access until revoked
+- They often have broader permissions than necessary
+
+Trusted publishing eliminates these risks by using short-lived, workflow-specific credentials that are automatically managed and cannot be extracted.
+
+### Handling private dependencies
+
+While trusted publishing handles the publish operation, you may still need authentication for installing private npm dependencies. For this scenario, we recommend:
+
+```yaml
+# GitHub Actions example
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    registry-url: 'https://registry.npmjs.org'
+
+# Ensure npm 11.5.0 or later for trusted publishing
+- run: npm install -g npm@latest
+
+# Use a read-only token for installing dependencies
+- run: npm ci
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}
+
+# Publish uses OIDC - no token needed
+- run: npm publish
+```
+
+Always use [read-only granular access tokens](/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) for installing dependencies. This limits potential damage if the token is ever compromised.
+
+### Additional security measures
+
+Consider implementing these additional security practices:
+
+- Use [deployment environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) to add approval requirements
+- Enable [tag protection rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) to control who can create release tags
+- Regularly audit your trusted publisher configurations
+- Remove any unused publish tokens from your npm account
+
+## Troubleshooting
+
+If you encounter an "Unable to authenticate" error when publishing, first verify that the workflow filename matches exactly what you configured on [npmjs.com](https://npmjs.com), including the `.yml` extension. The filename is case-sensitive and must be exact. Also ensure you're using GitHub-hosted runners or GitLab.com shared runners, as self-hosted runners are not currently supported. For GitHub Actions specifically, check that the `id-token: write` permission is set in your workflow.
+
+<Note>
+
+**Note:** npm does not verify your trusted publisher configuration when you save it. Double-check that your repository, workflow filename, and other details are correct, as errors will only appear when you attempt to publish.
+
+</Note>
+
+If your package has private dependencies and `npm install` or `npm ci` is failing with authentication errors, remember that trusted publishing only applies to the `npm publish` command. You'll still need to provide a read-only token for installing private packages as shown in the examples above.
+
+For packages in private repositories, provenance will not be generated even though you're using trusted publishing. This is a [known limitation](https://github.blog/changelog/2023-07-25-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/) that applies regardless of whether your package itself is public or private.
+
+## Limitations and future improvements
+
+Trusted publishing currently supports only cloud-hosted runners. Support for self-hosted runners is intended for a future release. Each package can only have one trusted publisher configured at a time, though you can update this configuration as needed.
+
+OIDC authentication is currently limited to the publish operation. Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods. The `npm whoami` command will not reflect OIDC authentication status since the authentication occurs only during the publish operation.
+
+We intend to expand trusted publishing support to additional CI/CD providers and enhance the feature based on community feedback.
+
+## Learn more
+
+- [About npm provenance](./generating-provenance-statements)
+- [OpenSSF Trusted Publishers specification](https://repos.openssf.org/trusted-publishers-for-all-package-repositories)
+- [GitHub Actions OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [GitLab CI/CD OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/)