npm provenance · SLSA practical guide 2026: Why package distribution security should be designed with OIDC, build proof, and approval gates before tokens

Created Date: 2026-07-08 · Category: Development Information

1. One-line problem definition

Key summary: The starting point of npm package deployment security is not “who distributed it,” but leaving verifiable information about “which workflow deployed it, with which source and through which build process.”

The target readers of this article are front-end and Node.js developers who operate public npm packages, in-house common library managers, and DevOps personnel in charge of release automation. The problem we are trying to solve is situations where long-term npm tokens remain in the CI, or where it is difficult to ensure that the deployed tarball is the same as the actual repository.

The scope is npm trusted publishing, provenance attestation, GitHub Actions-based distribution, and SLSA perspective verification. Exclusions include building a full private registry, comparing package signatures across all language ecosystems, and implementing full repro builds.

2. First, conclusion

Key summary: If you automatically distribute public npm packages, the default option as of 2026 is “OIDC-based trusted publishing + provenance + staged publishing when necessary”.

If you are creating a new package or tinkering with an existing package deployment pipeline, it is best to no longer make the long-term npm automation token your first choice. npm trusted publishing enables CI workflows to prove themselves to npm with OpenID Connect, a short-lived identity token.

However, it does not fit all teams immediately. Teams that only use self-hosted runners, teams that have fixed legacy Node versions, and teams that require people to check the tarball before publishing should design staged publishing and manual approval together.

3. Decomposition of core structure

Key takeaway: npm provenance is not a single signature, but a structure linking CI identity, build input, package output, and public verification log.

It is easy to understand if you look at the structure in four layers.

• Source layer: Git repository, tag, commit, and workflow files are the starting point for deployment.
• Execution layer: Supporting CIs such as GitHub Actions, GitLab CI, CircleCI are issued OIDC tokens.
• Proof layer: npm connects where and how it was built and distributed through provenance attestation and publish attestation.
• Verification layer: Consumer checks whether the registry signature and attestation are verified with the same command as npm audit signatures

SLSA's provenance model also sees the same problem. Describes which buildDefinition and runDetails the artifact comes from, and separates external input and build platform boundaries. From a novice developer’s perspective, it can be viewed as the “birth certificate of the package.”

4. Description of design intent

Key takeaway: The core intent of trusted publishing is not to better hide secrets, but to replace distribution permissions with workflow identities.

The existing npm token method is simple. Put a token in the CI secret, and the deployment job publishes to npm with that token. The problem is that the token lives for a long time, and there is a continuous burden in logs, cache, abuse of permissions, and account management of retired employees.

OIDC method works in reverse. Create a trust relationship in the npm package settings that says “Only this workflow file from this repository can be distributed” and briefly exchange tokens issued during CI execution. So even if stolen, it is difficult to reuse, and it is easy to track which workflow deployed it.

5. Evidence and Comparison

Key takeaways: The level of security should be determined by a combination of token lifetime, execution environment, approval steps, and verifiability rather than “do you have signing on?”

Based on npm document, trusted publishing requires npm CLI 11.5.1 or higher and Node 22.14.0 or higher. Staged publishing requires npm CLI 11.15.0 or higher and Node 22.14.0 or higher. This number is the reference point for deciding the build image and setup-node version in your actual transition plan.

6. Actual operation flow / step-by-step execution method

Key takeaway: It is safe to first create a tokenless publish path, then attach an attestation verification and approval loop.

Step 1: Register trusted publisher in npm package settings

Trusted Publisher in the package settings of npmjs.com. If you use GitHub Actions, enter organization/user, repository, workflow filename, and environment name if necessary. The workflow filename is not the full path, but a file name such as publish.yml.

Step 2: Create GitHub Actions workflow

name: Publish Package
on:
  push:
    tags:
      - 'v*'
permissions:
  contents: read
  id-token: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npm test
      - run: npm run build --if-present
      - run: npm publish

The key here is permissions: id-token: write. You must have this permission so GitHub Actions can request OIDC tokens. If trusted publishing is set up, npm CLI will detect the OIDC environment and use it before the traditional token method.

Step 3: When used in parallel with the existing provenance method

npm --version
node --version
npm publish --provenance --access public
npm audit signatures

third-party publish tool to bypass NPM_CONFIG_PROVENANCE=true, publishConfig.provenance=true, or .npmrc with provenance=true. However, this setting may be “prove-of-origin” and not “token removal” and must be distinguished from trusted publishing.

Step 4: High-risk packages change to staged publishing

npm stage publish
npm stage list @scope/package
npm stage view <stage-id>
npm stage download <stage-id>
npm stage approve <stage-id>

staged publishing does not upload CI directly to the live registry but submits it to the staging area. The maintainer must check the tarball and approve it with 2FA to make it public. Ideal for packages where trust is more important than operational speed.

7. Pitfalls

Key takeaways: Most failures occur when OIDC permissions, runner conditions, repository metadata, and approval permissions are roughly passed.

• Failure 1: id-token: write missing. OIDC token not issued prevents npm from authenticating with trusted publishing path. Prevention is to specify minimum privileges at the top of the workflow. Recovery involves adding permissions and checking the job log for OIDC detection before re-running the failed release tag.
• Failure 2: Use self-hosted runner. npm trusted publishing The document currently assumes a cloud-hosted runner. Prevention is to isolate only the publish job to GitHub-hosted runner. For recovery, even if the build is self-hosted, review the structure of verifying the publish artifact and then transferring it to a separate hosted publish job.
• Failure 3: The package.json repository does not match the actual source. Provenance links the public repository information with the build source, so the case must be correct. Prevention is to include npm pack --dry-run and package metadata check in CI before release.
• Failure 4: Provenance is misunderstood as a guarantee of the absence of malicious code. Provenance only shows where and how it was created, and is not a verdict that the code is safe. Prevention is to have CodeQL, dependency review, secret scan, tarball diff check together.

8. Strengths and Limitations

Key takeaways: This approach significantly increases deployment confidence, but is not a replacement for code review and vulnerability analysis.

The strengths are clear. Reduce long-term tokens, secure deployment workflow identities, and allow consumers to verify attestations and registry signatures. It is especially effective in libraries that have a large downstream impact, such as organization common packages.

The limits are also clear. If a malicious maintainer inserts malicious code in a normal workflow, provenance will only say that it was “created in a normal workflow.” Additionally, self-hosted CI, old Node images, and complex monorepo release tools make transition difficult.

9. Points to study more deeply

Key summary: Operational judgment becomes easier if you look at SLSA's buildDefinition/runDetails concept instead of just looking at the npm document.

• npm's trusted publishing configuration items: Decide which repository and workflow to trust.
• SLSA provenance's externalParameters: Understand what inputs the user can change.
• GitHub Actions OIDC claim: See how identity information like workflow, repository, ref, and environment goes into the token.
• staged publishing: Decide where to draw the line between automation and human approval.

10. Action Checklist + Author's Perspective

Key summary: If it is a public package, I recommend lowering token publish from the default and increasing trusted publishing to the default distribution path.

• The repository URL of package.json matches the actual public repository in upper and lower case letters.
• publish workflow runs in a supported environment such as GitHub-hosted/GitLab shared/CircleCI cloud.
• Node 22.14.0 or higher, npm CLI 11.5.1 or higher. For staged publishing, use npm 11.15.0 or higher.
In the
• workflow, contents: read and id-token: write are set as minimum privileges.
• The sequence of release tag creation, test, build, and publish remains as one auditable flow.
• npm audit signatures The results are stored as a verification log after release.
• Security-sensitive packages separate tarball review and 2FA approval through staged publishing.

Definition of Done: If publishing is successful without a token in the new release tag, and you can check the registry signature and attestation verification traces on the package page and npm audit signatures, the first conversion is complete.

From the author's point of view, a small experimental package managed by oneself can be started from npm publish --provenance. However, for libraries with users, SDKs common to the organization, and packages whose build results span multiple services, it is better to introduce trusted publishing first. The cost of leaking one long-term token is much greater than the cost of slowing down distribution by a few minutes per day.

Reference material

• npm Docs: Trusted publishing for npm packages, confirmation date 2026-07-08
• npm Docs: Generating provenance statements, confirmation date 2026-07-08
• npm Docs: Staged publishing for npm packages, confirmation date 2026-07-08
• npm Docs: About ECDSA registry signatures, confirmation date 2026-07-08
• SLSA Specification v1.1: Provenance, confirmation date 2026-07-08
• GitHub Docs: OpenID Connect, confirmation date 2026-07-08

WRITING-STANDARD Self-grading