Join our Newsletter — 33% off our NHI Course
Home› Guides› npm Trusted Publishing and Provenance Guide: OIDC Release…
Guide Software & AI Supply Chain

npm Trusted Publishing and Provenance Guide: OIDC Release Workflows Consumers Can Verify

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 8 November 2026 15 min read
On this page

Most npm package compromises still come down to one thing: an attacker gets hold of a credential that can publish, and the registry has no way to tell that release apart from a real one. npm trusted publishing replaces stored publish tokens with short-lived OpenID Connect (OIDC) credentials minted by a CI provider, and provenance attestations let anyone check which repository and workflow built a version. Both only help if the trust configuration is tight, the token path is actually closed and consumers verify what they install. This guide covers how the trust relationship works on the registry, who can change it, how to wire up GitHub Actions, GitLab CI/CD and CircleCI safely, what to monitor, and the mistakes that leave a package exposed after migration. It is for package maintainers, release engineers and platform teams who publish to the public npm registry. Facts were checked against npm's documentation on 27 October 2026; npm is changing this area quickly, so recheck version requirements before you roll out.

This is an independent guide from NHI Mgmt Group, based on npm's public documentation as of November 2026. It is not sponsored or reviewed by npm. Product features change, so confirm settings against npm's current documentation.

Key takeaways

  • The workflow becomes the credential. With trusted publishing there is no token to steal, so attackers target the release workflow, its triggers and the accounts that can edit it. Protect those as you would a signing key.
  • Adding a trusted publisher does not remove the old paths. npm accepts publishes from the configured workflow "in addition to" tokens and manual publishes until you set the package to "Require two-factor authentication and disallow tokens".
  • Stage-only is the strongest setting. A trusted publisher that may only run npm stage publish means every automated release waits for a maintainer to approve it with 2FA, and npm deliberately does not let OIDC approve stages.
  • Provenance proves origin, not safety. npm states plainly that provenance does not guarantee a package is free of malicious code; it gives a verifiable link to source and build instructions that someone still has to trust.
  • Verification is where the value lands. npm audit signatures and policies such as pnpm's trustPolicy: no-downgrade turn a missing or weaker attestation into a failed install instead of a silent compromise.

How identity and access work in npm trusted publishing

npm's implementation follows the OpenSSF trusted publishers model for package repositories. A maintainer registers a trust policy on the package that names a CI identity. At publish time the CI provider issues a signed OIDC ID token for the running job, the npm CLI detects the OIDC environment, exchanges that token with the registry for a short-lived publish credential, and the registry checks the token's claims against the policy. The CLI tries OIDC before it falls back to any configured token. Trusted publishing requires npm CLI 11.5.1 or later and Node.js 22.14.0 or later.

Provider (as supported today)Fields in the trust policyHow the job gets its tokenProvenance generated automatically
GitHub Actions, GitHub-hosted runnersOrganisation or user, repository, workflow file name (file name only, must live in .github/workflows/), optional environment, allowed actionspermissions: id-token: write on the jobYes, for a public package from a public repository
GitLab CI/CD, GitLab.com shared runnersNamespace, project, top-level CI file path, optional environment, allowed actionsid_tokens with NPM_ID_TOKEN audience npm:registry.npmjs.org, plus SIGSTORE_ID_TOKEN audience sigstoreYes, same conditions
CircleCI cloudOrganisation ID, project ID, pipeline definition ID (UUIDs), VCS origin, optional context IDs, allowed actionscircleci run oidc get with audience npm:registry.npmjs.org exported as NPM_ID_TOKENNo: npm does not currently generate provenance for CircleCI
Self-hosted runners on any providerNot supportedNot applicableNot applicable

Three properties of the trust policy matter for security. First, a new configuration must complete a successful publish within two days; that first publish "binds it to the repository's immutable identity", which addresses the OpenSSF concern that owner and repository names are mutable and can be re-registered by someone else. Second, npm does not validate a configuration when you save it, so a typo only shows up as an ENEEDAUTH error at publish time. Third, connections cannot be edited, only deleted and recreated. npm's website documentation allows up to 10 trusted publishers per package; the npm trust command reference we read on the same day still said the registry supports one configuration per package, so confirm current behaviour before designing around multiple publishers.

What the OIDC claims bind to

  • Repository and owner: the OpenSSF guidance says registries should match claims such as repository, repository_owner, repository_owner_id and workflow_ref, and must not rely only on generic claims like sub, iss and aud.
  • Workflow file name: the policy trusts a file name, and workflow files have no immutable ID. Anyone who can change that file on a branch that can trigger it can change what gets published.
  • Environment: optional, but it is the only field that ties the publish to a deployment gate you control, such as required reviewers or branch rules on a GitHub environment.
  • Reusable workflows: when a workflow uses workflow_call or workflow_dispatch to reach the job that runs npm publish, npm validates the calling workflow's name, and both parent and child need id-token: write.

Admin roles and privileged access

Trusted publishing moves privilege rather than removing it. The people who can change the trust policy, the package's publishing access setting or the release workflow now hold the keys.

Privileged actionWhere it happensWho can do itControl
Add, delete or replace a trusted publishernpmjs.com package settings, or npm trust github|gitlab|circleci, npm trust list, npm trust revoke --idMaintainers with write access; the CLI requires npm 11.15.0+, account-level 2FA and refuses granular tokens with bypass 2FAPhishing-resistant 2FA on every maintainer; review maintainer lists quarterly
Choose allowed actions: npm publish, npm dist-tagTrusted publisher configuration (--allow-publish, --allow-stage-publish)Same maintainersGrant stage publish only; enable "Allow npm dist-tag" only for a workflow that manages tags
Change publishing accessPackage Settings, Publishing accessMaintainersSet and keep "Require two-factor authentication and disallow tokens"
Approve a staged releasenpm stage approve <stage-id> or the Staged Packages tabA maintainer, with 2FA every timeInspect with npm stage view and npm stage download before approval
Edit the release workflow or CI fileSource repositoryAnyone with write access to a branch that can trigger itBranch and tag protection, CODEOWNERS on workflow files, required reviews
Approve a deployment environmentGitHub or GitLab environment settingsEnvironment reviewersRequired reviewers who are not the person who pushed the tag

Defaults have shifted during 2026. npm's documentation says configurations created before 20 May 2026 were set to allow npm publish only, and configurations created after 3 September 2026 default to npm stage publish, with direct publishing as an opt-in. Audit older configurations for direct publishing that nobody chose deliberately.

  • Staged publishing mechanics: it requires npm CLI 11.15.0 or later. npm stage publish itself does not need 2FA, which is why it suits CI; approval always does. For a brand new package, staging publishes a public placeholder version 0.0.0-stage.
  • What OIDC cannot do: npm limits OIDC to npm publish, npm stage publish and the dist-tag operations. Listing, viewing, approving or rejecting stages "require proof of presence", and install, view and access still need traditional authentication.
  • Maintainer accounts remain a path: an attacker who controls a maintainer's session can still change settings or approve a stage. See the Open Source Project Maintainer Security Guide for account hardening.

Integrations, API tokens and service accounts

Trusted publishing covers one operation. Release pipelines usually need other credentials too, and each should be the narrowest that works. Our npm Tokens Security Guide covers granular token settings in depth; this section covers how they fit around OIDC.

Need in the release jobCredentialNotes
Publish or stage the packageOIDC via trusted publishingNo stored secret; the exchanged registry token is short-lived and specific to the workflow
Install private dependencies before the buildRead-only granular token passed as NODE_AUTH_TOKEN only to the install stepnpm's own example: trusted publishing "is not intended for npm install"
Generate provenanceSigstore OIDC token (GitHub's id-token, GitLab's SIGSTORE_ID_TOKEN)Signed by Sigstore's public good instance and recorded in a public transparency log; review the Linux Foundation immutable record notice first
Self-hosted runner or unsupported CIGranular token, stage-only, scoped to named packagesA maintainer approves every staged version, so a stolen token cannot publish on its own
Move dist-tags such as latest or nextOIDC with "Allow npm dist-tag"Requires npm CLI 11.21.0 or later (or 12.2.0 or later); disabled by default
  • Grant id-token: write to the release job only: any step in a job with that permission can request an OIDC token for any audience the provider allows, including npm. Keep test, lint and pull request jobs without it. See the GitHub Actions OIDC Federation Hardening Guide.
  • Disable caching in release builds: npm's examples set package-manager-cache: false with the comment "never use caching in release builds". A cache written by a less trusted job can poison what the trusted job packs.
  • Keep install-time code out of the publishing job where you can: lifecycle scripts from dependencies run with the job's permissions. Build and test in one job, pass the packed tarball as an artefact, publish from a minimal job. See the npm Install-Time Security Guide.
  • Delete the old secret: once trusted publishing works, remove NPM_TOKEN from repository and organisation secrets and revoke the token on npm. A forgotten secret is still a publish path until tokens are disallowed.

The release workflow identity is a non-human identity with publish rights to everything that depends on you. Record it in your inventory with an owner, like any service account. See the CI/CD Pipeline Identity Security Guide.

Logging and detection

Provenance gives defenders something npm tokens never did: a public, signed record of where each version came from. Use it on both sides.

For maintainers

SignalSourceWhat it can mean
A version published without provenance on a package that normally has itRegistry metadata and the package pagePublish through a token or a maintainer session, bypassing the workflow
A publish with no matching tagged CI runCompare registry publish time with CI job historyOut-of-band publishing
Provenance that names an unexpected workflow, ref or repositoryAttestation contents and the transparency logA changed workflow or a second trusted publisher you did not expect
Trusted publisher added, removed or recreatedPackage settings, maintainer notification emails, npm trust listAccount takeover or an unreviewed change
Changes to workflow files, environments or tag rulesGitHub or GitLab audit logsPreparation for publishing from a modified workflow

For consumers

  • Registry signatures: npm audit signatures (npm CLI 8.15.0 or later) verifies the ECDSA registry signature on each installed version against the keys published at registry.npmjs.org/-/npm/v1/keys, and reports how many packages have verified attestations. It errors when signatures are missing but the registry provides keys, which can indicate a tampering mirror or proxy.
  • Trust downgrade checks: pnpm's trustPolicy: no-downgrade fails an install when a version has weaker trust evidence than an earlier-published version, for example a package previously released by a trusted publisher that now has only provenance or nothing. trustPolicyExclude and trustPolicyIgnoreAfter handle exceptions and old versions.
  • Keep the CLI current: npm notes the attestation format may change and that verification may need a newer npm than the one bundled with Node.js.

Map detections to T1195.002 Compromise Software Supply Chain for malicious releases and T1528 Steal Application Access Token for theft of publish credentials or OIDC tokens from a job.

Metrics

  • Trusted publishing coverage: share of your public packages released only through trusted publishing with tokens disallowed. Target 100%.
  • Stage-only coverage: share of widely used packages whose trusted publisher may only stage.
  • Provenance continuity: versions in the last 90 days without provenance on packages that have it, target zero.
  • Write tokens remaining: count of write-capable npm tokens across maintainer accounts, trending to zero.
  • Consumer verification: share of CI pipelines running npm audit signatures or a no-downgrade trust policy.

Hardening baseline

  1. Inventory publish paths: list every package, its maintainers, every token secret in CI, and every release line (including old major versions maintained from other branches).
  2. Prepare the workflow: a dedicated release workflow triggered by protected tags or releases, a deployment environment with required reviewers, id-token: write on the publish job only, no caching, pinned actions, npm CLI 11.5.1 or later. Make sure repository.url in package.json matches the repository exactly.
  3. Register the trusted publisher: on npmjs.com or with npm trust, naming the workflow file and environment, with stage publish only for high-impact packages. Complete the first publish within two days.
  4. Test: publish a prerelease, confirm provenance appears and that the attestation names the expected workflow and ref, and run npm audit signatures in a consumer project.
  5. Close the token path: set "Require two-factor authentication and disallow tokens", delete NPM_TOKEN secrets and revoke the tokens.
  6. Repeat for every release line: each package has one publishing access setting, but teams often forget maintenance branches that still use a token.
  7. Rollback: if a release fails, delete and recreate the trusted publisher rather than re-enabling tokens, and keep a documented break-glass path: an interactive publish or stage approval by a named maintainer with a security key.

Decision guidance

  • Direct publish versus stage-only: direct publishing suits small packages with frequent releases and a single maintainer who accepts the risk. Stage-only suits anything with many dependants, at the cost of a human step per release. npm's newer defaults already lean to stage-only.
  • GitHub, GitLab or CircleCI: choose the provider your code already uses; if provenance matters to your consumers, note that CircleCI publishes do not get it today.
  • Self-hosted runners: move the publish job to a hosted runner, keep everything else self-hosted, and pass the tarball as an artefact. If that is impossible, use a stage-only granular token.
  • Small project versus large organisation: a solo maintainer can get most of the value from trusted publishing plus disallowed tokens. An organisation with hundreds of packages should script configuration with npm trust (npm documents bulk use within a five-minute 2FA skip window), keep a central register of trust policies and review them quarterly.

Common misconfigurations

  • Trusted publishing on one release line, a token on another: a token left on any release line remains a publish path. Disallow tokens for the whole package and treat maintainer sessions as a publish path.
  • Leaving tokens allowed after migration: without the publishing access change, a stolen token works exactly as before.
  • Granting id-token: write at workflow level: every job, including ones that run pull request code or third-party actions, can then mint a token the registry will accept.
  • Trusting a workflow that untrusted events can trigger: a policy that names publish.yml is only as strong as the rules on what can run that file. Combine tag triggers, environment reviewers and protection on .github/workflows/.
  • Treating provenance as a safety verdict: a compromised workflow produces valid provenance. Consumers should verify the attestation names the expected repository and workflow, and watch for downgrades, rather than accepting "has provenance" as enough.
  • Stale configurations: trusted publishers for renamed repositories, archived workflows or former CI providers remain valid trust anchors until deleted.

A token stolen from a developer machine or CI can republish every package it reaches. A package that accepts only stage-only OIDC publishes from a protected workflow breaks that chain.

Framework mapping

FrameworkReferenceHow it applies
NIST SP 800-53 Rev. 5SR-4 Provenance, SR-11 Component AuthenticityProvenance attestations and registry signature verification
NIST SP 800-53 Rev. 5IA-5 Authenticator ManagementReplacing long-lived publish tokens with short-lived OIDC credentials
NIST SP 800-53 Rev. 5SA-10 Developer Configuration Management, SI-7.15 Code AuthenticationProtected release workflows and signed, verifiable releases
NIST CSF 2.0PR.AA-01, PR.PS-06, ID.RA-09Managed workload credentials for publishing; secure development practices; consumers assessing software authenticity before use
SLSABuild track provenancenpm provenance from hosted CI is a practical way to publish build provenance; see the SLSA and Build Provenance Guide
MITRE ATT&CK v20T1195.002, T1528Malicious releases and theft of publish credentials

Practitioner checklist

  • Inventory every package, maintainer, release line and stored npm token before migrating.
  • Use npm CLI 11.5.1 or later for trusted publishing, 11.15.0 or later for staged publishing and npm trust.
  • Register a trusted publisher per package with workflow file and environment set, stage-only for high-impact packages, and finish the first publish within two days.
  • Give id-token: write to the publish job only, disable caching in release builds and keep dependency lifecycle scripts out of that job.
  • Set "Require two-factor authentication and disallow tokens" on every package, then delete NPM_TOKEN secrets and revoke the tokens.
  • Protect workflow files, release tags and deployment environments with reviewers and CODEOWNERS.
  • Alert on versions without provenance, publishes without a matching CI run and changes to trusted publisher configurations.
  • Run npm audit signatures in consuming pipelines and consider a no-downgrade trust policy where your package manager supports one.
  • Review trusted publisher configurations quarterly, including ones created before npm changed its defaults in 2026.

Standards and references

Related NHI Mgmt Group resources: npm Tokens Security Guide · SLSA and Build Provenance Guide · PyPI API Tokens and Trusted Publishing Security Guide · Sigstore Guide · Node.js Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 8 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.