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 publishmeans 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 signaturesand policies such as pnpm'strustPolicy: no-downgradeturn 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 policy | How the job gets its token | Provenance generated automatically |
|---|---|---|---|
| GitHub Actions, GitHub-hosted runners | Organisation or user, repository, workflow file name (file name only, must live in .github/workflows/), optional environment, allowed actions | permissions: id-token: write on the job | Yes, for a public package from a public repository |
| GitLab CI/CD, GitLab.com shared runners | Namespace, project, top-level CI file path, optional environment, allowed actions | id_tokens with NPM_ID_TOKEN audience npm:registry.npmjs.org, plus SIGSTORE_ID_TOKEN audience sigstore | Yes, same conditions |
| CircleCI cloud | Organisation ID, project ID, pipeline definition ID (UUIDs), VCS origin, optional context IDs, allowed actions | circleci run oidc get with audience npm:registry.npmjs.org exported as NPM_ID_TOKEN | No: npm does not currently generate provenance for CircleCI |
| Self-hosted runners on any provider | Not supported | Not applicable | Not 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_idandworkflow_ref, and must not rely only on generic claims likesub,issandaud. - 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_callorworkflow_dispatchto reach the job that runsnpm publish, npm validates the calling workflow's name, and both parent and child needid-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 action | Where it happens | Who can do it | Control |
|---|---|---|---|
| Add, delete or replace a trusted publisher | npmjs.com package settings, or npm trust github|gitlab|circleci, npm trust list, npm trust revoke --id | Maintainers with write access; the CLI requires npm 11.15.0+, account-level 2FA and refuses granular tokens with bypass 2FA | Phishing-resistant 2FA on every maintainer; review maintainer lists quarterly |
Choose allowed actions: npm publish, npm dist-tag | Trusted publisher configuration (--allow-publish, --allow-stage-publish) | Same maintainers | Grant stage publish only; enable "Allow npm dist-tag" only for a workflow that manages tags |
| Change publishing access | Package Settings, Publishing access | Maintainers | Set and keep "Require two-factor authentication and disallow tokens" |
| Approve a staged release | npm stage approve <stage-id> or the Staged Packages tab | A maintainer, with 2FA every time | Inspect with npm stage view and npm stage download before approval |
| Edit the release workflow or CI file | Source repository | Anyone with write access to a branch that can trigger it | Branch and tag protection, CODEOWNERS on workflow files, required reviews |
| Approve a deployment environment | GitHub or GitLab environment settings | Environment reviewers | Required 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 publishitself does not need 2FA, which is why it suits CI; approval always does. For a brand new package, staging publishes a public placeholder version0.0.0-stage. - What OIDC cannot do: npm limits OIDC to
npm publish,npm stage publishand the dist-tag operations. Listing, viewing, approving or rejecting stages "require proof of presence", andinstall,viewandaccessstill 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 job | Credential | Notes |
|---|---|---|
| Publish or stage the package | OIDC via trusted publishing | No stored secret; the exchanged registry token is short-lived and specific to the workflow |
| Install private dependencies before the build | Read-only granular token passed as NODE_AUTH_TOKEN only to the install step | npm's own example: trusted publishing "is not intended for npm install" |
| Generate provenance | Sigstore 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 CI | Granular token, stage-only, scoped to named packages | A maintainer approves every staged version, so a stolen token cannot publish on its own |
Move dist-tags such as latest or next | OIDC 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: writeto 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: falsewith 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_TOKENfrom 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
| Signal | Source | What it can mean |
|---|---|---|
| A version published without provenance on a package that normally has it | Registry metadata and the package page | Publish through a token or a maintainer session, bypassing the workflow |
| A publish with no matching tagged CI run | Compare registry publish time with CI job history | Out-of-band publishing |
| Provenance that names an unexpected workflow, ref or repository | Attestation contents and the transparency log | A changed workflow or a second trusted publisher you did not expect |
| Trusted publisher added, removed or recreated | Package settings, maintainer notification emails, npm trust list | Account takeover or an unreviewed change |
| Changes to workflow files, environments or tag rules | GitHub or GitLab audit logs | Preparation 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 atregistry.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-downgradefails 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.trustPolicyExcludeandtrustPolicyIgnoreAfterhandle 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 signaturesor a no-downgrade trust policy.
Hardening baseline
- 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).
- Prepare the workflow: a dedicated release workflow triggered by protected tags or releases, a deployment environment with required reviewers,
id-token: writeon the publish job only, no caching, pinned actions, npm CLI 11.5.1 or later. Make surerepository.urlinpackage.jsonmatches the repository exactly. - 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. - Test: publish a prerelease, confirm provenance appears and that the attestation names the expected workflow and ref, and run
npm audit signaturesin a consumer project. - Close the token path: set "Require two-factor authentication and disallow tokens", delete
NPM_TOKENsecrets and revoke the tokens. - Repeat for every release line: each package has one publishing access setting, but teams often forget maintenance branches that still use a token.
- 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: writeat 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.ymlis 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
| Framework | Reference | How it applies |
|---|---|---|
| NIST SP 800-53 Rev. 5 | SR-4 Provenance, SR-11 Component Authenticity | Provenance attestations and registry signature verification |
| NIST SP 800-53 Rev. 5 | IA-5 Authenticator Management | Replacing long-lived publish tokens with short-lived OIDC credentials |
| NIST SP 800-53 Rev. 5 | SA-10 Developer Configuration Management, SI-7.15 Code Authentication | Protected release workflows and signed, verifiable releases |
| NIST CSF 2.0 | PR.AA-01, PR.PS-06, ID.RA-09 | Managed workload credentials for publishing; secure development practices; consumers assessing software authenticity before use |
| SLSA | Build track provenance | npm provenance from hosted CI is a practical way to publish build provenance; see the SLSA and Build Provenance Guide |
| MITRE ATT&CK v20 | T1195.002, T1528 | Malicious 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: writeto 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_TOKENsecrets 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 signaturesin 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
- npm Docs: Trusted publishing for npm packages
- npm Docs: Generating provenance statements
- npm Docs: Staged publishing for npm packages
- npm Docs: Verifying ECDSA registry signatures
- npm Docs: npm-trust command
- OpenSSF: Trusted Publishers for All Package Repositories
- pnpm: Settings, trustPolicy and minimumReleaseAge
- NIST: SP 800-53 Rev. 5
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