Using sigstore and cosign to Verify npm Packages Have Not Been Tampered With

Traditional code signing requires a signing key that must be stored securely, rotated periodically, and revoked if compromised. Stolen signing keys are a major attack vector, a stolen key lets an attacker sign arbitrary packages as a legitimate maintainer.

sigstore eliminates the long-lived key problem with a keyless signing model:

1. The developer (or CI system) authenticates via OIDC, in a GitHub Actions context, this is the same OIDC token used for cloud provider authentication.
2. Fulcio (sigstore's certificate authority) issues a short-lived X.509 signing certificate that expires in 10 minutes, bound to the OIDC identity (e.g., the GitHub Actions workflow URL).
3. The package is signed with this ephemeral certificate.
4. The signature and a certificate verification bundle are recorded in Rekor, sigstore's append-only transparency log.
5. At verification time, anyone can retrieve the certificate and signature from Rekor and verify that the package was signed by the claimed identity during the claimed build.

The result: there is no long-lived key for an attacker to steal. A malicious actor who compromises the package registry cannot retroactively create a valid sigstore signature for a tampered package, they would need to also compromise the OIDC identity at the time of publication.

npm's provenance feature, released in 2023, is sigstore integration built into the npm CLI. When you publish with --provenance from a GitHub Actions workflow, npm automatically:

• Requests a sigstore certificate for your workflow's OIDC identity
• Signs the package tarball
• Records the signature in Rekor
• Attaches the provenance statement to your package on the registry

To enable it, add --provenance to your publish command in your GitHub Actions workflow:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for sigstore OIDC
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

After publishing, your package page on npmjs.com shows a provenance badge linking to the Rekor entry and the specific GitHub Actions run that built the package.

Verifying provenance before installing a package confirms it was built from the claimed repository by an authenticated CI system.

Using npm audit signatures:

npm audit signatures

This command verifies the registry signatures for all packages in your current node_modules. It does not verify provenance (build source), but it confirms the packages match what the registry served, detecting a man-in-the-middle or a registry compromise.

Checking provenance for a specific package:

npm view @tanstack/react-router --json | jq '.dist.attestations'

This returns the attestation metadata including the Rekor log ID and the GitHub Actions workflow that built the package. Cross-reference the workflow URL against the official TanStack repository.

Using the sigstore CLI for deeper verification:

# Install cosign
brew install cosign

# Verify an npm package's provenance
cosign verify-npm-provenance @tanstack/react-router@1.120.0

This verifies the OIDC identity that signed the package matches the expected GitHub repository and workflow path.

Verification in developer workflows is valuable, but verification in CI, before a build uses a dependency, catches tampered packages before they reach any developer machine.

Add this step to your CI workflow after npm ci:

- name: Verify npm package provenance
  run: |
    # Verify signatures for all installed packages
    npm audit signatures
    
    # For critical dependencies, verify provenance explicitly
    PACKAGES="@tanstack/react-router react react-dom"
    for pkg in $PACKAGES; do
      version=$(node -e "console.log(require('./node_modules/$pkg/package.json').version)")
      echo "Verifying $pkg@$version"
      npm view "$pkg@$version" --json | jq -e '.dist.attestations // error("No provenance")' || \
        echo "WARNING: $pkg has no provenance attestation"
    done

This approach fails fast if any critical dependency lacks provenance or has an invalid signature. Over time, as more packages adopt provenance, you can convert warnings to hard failures.

If your Node.js application ships as a Docker image, cosign extends the same verification model to container images.

Signing an image after build in GitHub Actions:

- name: Sign container image
  run: |
    cosign sign --yes \
      ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build.outputs.digest }}
  env:
    COSIGN_EXPERIMENTAL: '1'

Verifying before deployment:

cosign verify \
  --certificate-identity-regexp 'https://github.com/yourorg/yourrepo/.github/workflows/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  your-registry/your-image:tag

This confirms the image was built by your GitHub Actions workflow and not modified after push. In a Kubernetes environment, integrate this with Kyverno or OPA policies that reject pods using images without a valid cosign signature.

npm audit signatures failure means one of:

1. The package was modified after being published to the registry (tampering)
2. The package was published to a mirror registry and the signature does not match
3. The npm registry served a different version than the one you requested

For a package with no provenance attestation, it means the package was published without provenance, which describes most packages today. Treat the absence of provenance as a risk factor, not an automatic failure, until your critical dependencies all have provenance.

For a provenance mismatch, where the provenance exists but points to a different repository or workflow than expected, treat it as a security incident. Remove the package from your node_modules immediately, audit your lockfile for the commit that introduced it, and check whether your CI ran with the tampered package already installed.