Record provenance and signatures

A checksum detects change only when the expected checksum arrives through a trusted channel. Provenance connects the artifact to its build process: which source revision, which builder, which workflow produced these exact bytes.

The modern tooling for this is Sigstore. Instead of long-lived signing keys that can be stolen, the build workflow signs with a short-lived certificate tied to its identity — for GitHub Actions, the repository and workflow path — and the signature is recorded in a public transparency log.

Publish npm packages with provenance

For npm packages this is nearly free. In the release workflow, grant an OIDC token and publish with the provenance flag:

permissions:
  id-token: write
  contents: read

npm publish --provenance

npm now attaches a Sigstore-backed attestation linking the published tarball to the exact repository, commit, and workflow run that built it. Generate attestations inside the trusted builder, and sign through a protected identity or key — never on a laptop after the fact.

Consumers can check the whole tree:

npm audit signatures
# audited 212 packages in 3s
# 212 packages have verified registry signatures
# 14 packages have verified attestations

If a package’s bytes do not match what the registry signed, this command fails loudly.

A valid signature is not enough

Verification needs policy, not just cryptography. An attacker signs a package from a personal workflow using a valid identity. The signature verifies mathematically, but the artifact did not come from the protected release workflow or approved source revision.

So consumers must verify the signature, the expected project, the source revision, the builder identity, and the artifact digest. With cosign that policy is explicit:

cosign verify ghcr.io/acme/api:1.4.2 \
  --certificate-identity-regexp 'github.com/acme/api/.github/workflows/release.yml' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

This rejects anything not signed by that specific workflow, even if the signature itself is valid.

Choose one release artifact and write the exact provenance policy a consumer should enforce. Save a successful verification showing its subject digest, source revision, and builder identity. Then verify a valid attestation from an unapproved branch or builder and prove the policy rejects it.