docs: add release provenance guidance

[samayer12]

Summary

• document GitHub and npm provenance verification for Pepr releases
• explain how consumers should evaluate attestation identities and digests
• describe the post-publish verification job and current SLSA Build L2 assurance
• record the release invariants maintainers must preserve
• link the guide from Pepr security best practices

Stack

• Depends on ci: verify published release provenance #3344
• This PR contains only the provenance documentation layer

Validation

• markdownlint passes
• release workflow passes Prettier validation
• git diff --check passes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.98%. Comparing base (a8af08b) to head (829eefc).

Additional details and impacted files

@@                      Coverage Diff                      @@
##           ci/verify-release-provenance    #3343   +/-   ##
=============================================================
  Coverage                         77.98%   77.98%           
=============================================================
  Files                                92       92           
  Lines                              2548     2548           
  Branches                            545      545           
=============================================================
  Hits                               1987     1987           
  Misses                              439      439           
  Partials                            122      122           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Confidence Score: 5/5

The documentation-only change appears safe to merge, with no concrete correctness, security, or integration issue identified.

Summary

This PR adds consumer and maintainer guidance for verifying Pepr npm release provenance.

• Documents GitHub Artifact Attestation and npm provenance verification.
• Explains attestation identity, digest, source, and SLSA assurance.
• Records the release workflow's artifact-identity invariants and historical provenance baseline.
• Links the new guidance from the security best-practices page.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  B[Build npm tarball once] --> D[Record SHA-256 digest]
  D --> A[Verify digest and create GitHub attestation]
  A --> P[Verify digest and publish through npm]
  P --> V[Download published package]
  V --> C[Compare build and published digests]
  C --> G[Verify GitHub attestation]
  C --> N[Verify npm signatures and provenance]
  P --> O[Verify digest and push OCI package]

Loading

_{Reviews (1) · Last reviewed commit: "docs: add release provenance guidance"}