Check an approved npm archive with OpenSSL or GnuPG

Check who signed an npm archive and whether it matches the exact bytes your release owners approved in KeySigner.

Before you start

KeySigner release history and OpenSSL. KeySigner release history and GnuPG with --assert-signer

  • Use a test npm archive, its detached RSA signature with SHA-256, the publisher’s trusted PEM key and the approved digest from KeySigner.
  • Use a test npm archive, its detached OpenPGP signature, the independently verified publisher fingerprint and the approved digest from KeySigner.

Data and access

Shared or checked
KeySigner’s approval names the package digest. OpenSSL or GnuPG checks the detached signature against the downloaded archive and trusted publisher key.
Check separately
The package publisher’s signature and the release owners’ approval must both refer to the same archive. Registry permissions remain separate.

Who does what

Release owners
Approve the SHA-256 of the packaged archive in KeySigner.
Publisher
Signs the archive and supplies the detached signature in the format used by your release process.
Release reviewer
Verifies the signature against the expected publisher and compares the archive with the approved digest.
  1. Get the archive, signature and approval

    In the test KeySigner release, confirm that the configured owners approved the intended npm package, version and source run. Save the approved SHA-256. Keep the exact .tgz file and the detached signature together. Use the publisher key or fingerprint from your trusted release policy.

    Choose the verification command for your signature

    OpenSSL
    Use the OpenSSL example for an RSA signature with SHA-256 and a trusted PEM public key.
    GnuPG
    Use the GnuPG example for a detached OpenPGP signature and an independently confirmed publisher fingerprint.

    Check. The request is approved and records the package, version, source run and exact archive digest.

  2. Verify an RSA signature with OpenSSL

    For an RSA signature made with SHA-256, set publisher-public.pem to the public key pinned by your release policy. Replace the sample filenames with the detached signature and the matching npm archive. Stop if verification fails.

    openssl dgst -sha256 -verify publisher-public.pem \
      -signature archive.sig package-1.0.0.tgz

    Check. OpenSSL reports Verified OK with the expected key. A different key or different archive fails.

  3. Verify an OpenPGP signature with GnuPG

    For OpenPGP, import the publisher’s public key into the test keyring. Put the expected fingerprint from your release policy on one line in publisher-fingerprint.txt, without spaces. Use a GnuPG build with --assert-signer. Stop if the signature or fingerprint check fails.

    gpg --batch --assert-signer publisher-fingerprint.txt \
      --verify archive.gpg package-1.0.0.tgz

    Check. GnuPG exits successfully with the expected signer fingerprint. A good signature from a different key does not satisfy the fingerprint check.

  4. Compare the signed archive with the approval

    Compute SHA-256 on the same .tgz you verified. Compare all 64 hexadecimal characters with the approved digest in KeySigner after the sha256: prefix. The release requester or a KeySigner administrator can record the observed digest for the request.

    shasum -a 256 package-1.0.0.tgz

    Check. The computed digest equals the approved SHA-256. KeySigner records a match if the requester or administrator submits it.

  5. Try a separately signed replacement

    In the test workspace, change a file and pack a second archive with the same package name and version. Have the same test publisher sign the replacement. Verify its own detached signature, then compare its SHA-256 with the original approval. Keep both archives off the public npm registry.

    Check. The publisher check can pass for the replacement. KeySigner records a mismatch when you submit the replacement digest against the original approval.

Check your result

Confirm both the expected publisher signature and the approved digest for the same archive before releasing it. Keep the approval ID, source run, publisher identifier and archive digest with your release record.

What we tested

Tested on . OpenSSL 4.1.0 and GnuPG 2.5.22 verified signatures for two local npm archives from the same test publisher. Each verifier rejected the original signature against the changed archive and rejected the wrong publisher. In a local KeySigner release rehearsal, two owners approved the original archive and KeySigner recorded a match for it and a mismatch for the signed replacement.

How to verify your setup

If you get stuck

The signature is valid and the approved digest differs

Pause the release and compare the archive you received with the build output. Packaging the same version again can yield different bytes. If the replacement is intended, request approval for its own digest.

Report a problem with this guide

Explore all setup guides →