Before you start
KeySigner release history and Cosign
- Have the test npm archive, its Sigstore bundle and the approved SHA-256 from the KeySigner request.
- Get the expected signing identity and OIDC issuer from your release policy.
Data and access
Record the approved archive
In a test KeySigner release, use the exact npm archive the workflow plans to publish. After the configured owners approve, record the request ID, package and version, SHA-256 digest and source run. Obtain the signed archive and its Sigstore bundle from your test publisher.
Check. The request shows the exact archive digest. Its state changes from Waiting for owners to Approved when the configured number of owners approve.
Verify the publisher and archive
For a keyless bundle, set EXPECTED_IDENTITY and EXPECTED_ISSUER from your release policy. Run Cosign on the downloaded archive and its bundle. Stop if verification fails.
cosign verify-blob --bundle "$SIGSTORE_BUNDLE" \ --certificate-identity "$EXPECTED_IDENTITY" \ --certificate-oidc-issuer "$EXPECTED_ISSUER" "$PACKAGE_ARCHIVE"Check. Cosign reports Verified OK for the archive and expected publisher. Verification fails if you reuse that bundle on a different archive.
Compare the signed bytes with the approval
Compute SHA-256 on the same file you gave Cosign. Compare all 64 hexadecimal characters with the digest on the approved request, after the sha256: prefix. The release requester or a KeySigner administrator can record the observed digest with that request.
shasum -a 256 "$PACKAGE_ARCHIVE"Check. The signed file matches the SHA-256 recorded on the approved request. If you report that digest, KeySigner records a matching check.
Rehearse a signed replacement
Create a different archive with the same package name and version. Have the test publisher sign that new archive separately. Verify its own bundle against the same publisher policy, then compare its digest with the original approval. Keep the rehearsal off the public npm registry.
Check. Cosign can accept the separately signed replacement. KeySigner records a digest mismatch when you submit its different digest against the original request.
Check your result
Proceed only after both checks pass for the same archive. Keep the KeySigner request ID, verified publisher identity, source run and archive digest together so you can trace the release.
What we tested
Tested on . Cosign 3.1.4 verified the public Cosign release binary with its keyless bundle and rejected modified bytes. In a separate KeySigner rehearsal, two owners approved the SHA-256 of a local npm tarball. A disposable signing key produced bundles that Cosign verified for both the original and replacement tarballs. KeySigner recorded a mismatch for the signed replacement and a match for the original.
If you get stuck
Cosign verifies the archive but the digest differs
Pause the release. Compare the approved digest, the digest on the original build output and the SHA-256 of the archive you received. A second npm pack can produce different bytes if its inputs changed. If you intend to publish the new archive, review and request approval for its new digest.