[ADVANCED]: cryptographically sign releases

[exploreriii]

🧠 Advanced Contributors — Prerequisites & Expectations

🐞 Problem Description

We part of the open SSF scorecard we should cryptographically sign releases
https://scorecard.dev/viewer/?uri=github.com/hiero-ledger/hiero-sdk-python

read about it:
https://github.com/ossf/scorecard/blob/c0df03399ddd8c3345b62ff3df813f3cbbe5bf42/docs/checks.md#signed-releases

We may be able to achieve this using
https://github.com/sigstore/sigstore-python

The issue would be to edit our publish workflow, https://github.com/hiero-ledger/hiero-sdk-python/blob/main/.github/workflows/publish.yml, or, create a new release sign workflow to ensure we are signing releases.

We should consider what kind of permissions will be required to achieve that, and some kind of openness how to test or simulate this

Caution

This advanced issue requires independent research and testing.

🏁 Concrete Prerequisites

• Proven History: Successfully merged ≥ 3 non-trivial intermediate issues in this repo, including at least 2 relating to github actions.
• Expertise: good architectural understanding of creating high-quality, well tested workflows

⚠️ AI Usage Policy

Using AI to generate code for Advanced issues is strictly discouraged. AI may be used only to help explain file relationships. We require this workflow to work and follow best principles.

⏱️ Timeline & Workflow

• Typical time: ~2 weeks / ~20 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Advised: Post your proposed architectural approach as a comment and wait for feedback before writing any code.

🛠️ Implementation Notes

Technical domains involved in this issue:

• CI/CD Integration
• Signing Research
• Workflow Optimization
  Streamlining the pipeline by replacing multiple tools (e.g. Flake8 and plugins) with Ruff, reducing CI runtime while maintaining coverage.

🛡️ Quality & Review Standards

The bar for advanced PRs is "safe, maintainable, architecturally sound, and production-ready."

• CI Reliability. Workflow must run consistently on appropriate trigger
• Proper lowest permissions set to limited scope files
• Package is signed in a meaningful and appropriate way
• Workflow file is simple, readable, and minimal. Uses stable, well-supported GitHub Actions with hashes.

Notably: Developer architects the solution of how to best apply bandit to the repo

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current architectural approaches.
• I have tested my changes extensively against both local and network environments.
• Every line of code is personally understood and explainable and tested

📚 Resources & Support

Sample from github:

Project References:

• SDK Project Structure
• Transaction Lifecycle
• Hedera Protobufs (v0.72.0-rc.2)

🆘 Stuck?

• Office Hours (Wednesdays, 2pm UTC)
• Discord #hiero-python-sdk

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Enable PyPI attestations by adding attestations: true to the existing pypa/gh-action-pypi-publish action, leveraging the already-configured OIDC Trusted Publishing
• Sign release artifacts using sigstore/gh-action-sigstore-python to produce Sigstore bundles (.sigstore.json files) containing cryptographic signatures anchored to the Rekor transparency log
• Create GitHub Releases with both original artifacts and their signature bundles attached, making signed releases visible to the OpenSSF Scorecard
• Maintain existing security patterns: SHA-pinned actions, harden-runner, minimal permissions elevated only at job level

Design Choices

Design Choice 1: Signing Approach: PyPI Attestations vs GitHub Release Signing

Options Considered:

1. Enable PyPI attestations only (minimal change via attestations: true)
2. Add GitHub Release signing only (for scorecard visibility)
3. Both PyPI attestations and GitHub Release signing

Chosen Option: 3

Rationale: Option 3: Both approaches provide comprehensive coverage—PyPI attestations verify packages on the registry, while GitHub Release signatures are directly visible to the OpenSSF Scorecard and users who download from GitHub.

Design Choice 2: Workflow Structure: Modify Existing vs Create New

Options Considered:

1. Modify publish.yml to add signing and release creation in the same job
2. Create a separate release.yml workflow triggered after publish
3. Add a second job to publish.yml that runs after the publish job

Chosen Option: 1

Rationale: Option 1: Modifying the existing publish.yml keeps the workflow simple, ensures signing happens atomically with publishing, and aligns with the ticket's primary suggestion. A single job maintains artifact availability without needing inter-job artifact passing.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Enable Signed Releases in Publish Workflow

Enhance the existing publish workflow to enable PyPI attestations, sign artifacts with Sigstore, and create a GitHub Release with the signed artifacts attached.

Task 1: Add Required Permissions

Update the job-level permissions in publish.yml to support attestation generation and GitHub Release creation.

• Add attestations: write permission to the build-and-publish job for PyPI attestation generation
• Add contents: write permission to enable creating GitHub Releases and uploading assets
• Keep id-token: write for OIDC authentication (already present)
• Maintain workflow-level contents: read as the restrictive default

Task 2: Enable PyPI Attestations

Configure the PyPI publish action to generate Sigstore-backed attestations.

• Add attestations: true parameter to the pypa/gh-action-pypi-publish action step
• This enables automatic Sigstore signing of uploaded packages, creating verifiable links from PyPI artifacts back to the source repository and workflow

Task 3: Add Artifact Signing Step

Add a step to sign the built artifacts using the official Sigstore GitHub Action before creating the release.

• Add sigstore/gh-action-sigstore-python action after the build step and before the PyPI publish step
• Configure to sign all files in dist/ directory (wheel and sdist)
• Pin the action to a specific SHA hash following codebase conventions
• The action produces .sigstore.json bundle files (containing signature, certificate, and Rekor transparency log entry) for each signed artifact

Task 4: Create GitHub Release with Signed Artifacts

Add a step to create a GitHub Release and attach both the original artifacts and their Sigstore signatures.

• Add softprops/action-gh-release action (or equivalent) as the final step, pinned to SHA hash
• Configure to trigger only on tag pushes (the existing workflow trigger)
• Upload dist/* contents including original artifacts (.whl, .tar.gz) and signature bundles (.sigstore.json)
• Use the tag name as the release name
• Enable draft mode initially if manual review before publish is desired (configurable based on project preferences)

Task 5: Maintain Security Hardening

Ensure the modified workflow maintains existing security practices.

• Keep step-security/harden-runner as the first step
• Verify all new actions are pinned to full SHA hashes with version comments
• Confirm egress-policy: audit is maintained for network monitoring

🤖 Prompt for AI agents

Enhance `.github/workflows/publish.yml` to add cryptographic signing of release
artifacts and creation of a GitHub Release. The goal is to enable PyPI
attestations, sign artifacts with Sigstore, and attach signed artifacts to a new
GitHub Release.

**1. Update job-level permissions on the `build-and-publish` job:**
- Add `attestations: write` (for PyPI attestation generation)
- Add `contents: write` (for creating GitHub Releases and uploading assets)
- Retain the existing `id-token: write` permission
- Keep workflow-level `contents: read` as the restrictive default

**2. Enable PyPI attestations:**
- In the existing `pypa/gh-action-pypi-publish` step, add the parameter
`attestations: true`

**3. Add an artifact signing step:**
- Insert a new step using `sigstore/gh-action-sigstore-python`, placed **after**
the build step and **before** the PyPI publish step
- Configure it to sign all files in the `dist/` directory (both wheel and sdist)
- Pin the action to a full SHA hash, with a version comment, following existing
codebase conventions
- This step produces `.sigstore.json` bundle files alongside each artifact

**4. Add a GitHub Release creation step:**
- Add a new final step using `softprops/action-gh-release` (or equivalent),
pinned to a full SHA hash with a version comment
- Upload all contents of `dist/*`, including original artifacts (`.whl`,
`.tar.gz`) and signature bundles (`.sigstore.json`)
- Use the triggering tag name as the release name
- Optionally enable draft mode for manual review (configurable)

**5. Maintain security hardening:**
- Ensure `step-security/harden-runner` remains the first step in the job
- Confirm all newly added actions are pinned to full SHA hashes with version
comments
- Confirm `egress-policy: audit` is still present

Phase 2: Documentation Updates

Update project documentation to reflect the new signing process and provide verification instructions.

Task 1: Update Release Documentation

Enhance RELEASE.md to document the signing process and its outputs.

• Add a section explaining that releases are now cryptographically signed using Sigstore
• Document that both PyPI attestations and GitHub Release signatures are generated
• Describe the artifacts produced: .sigstore.json bundles containing signature, certificate, and transparency log proof

Task 2: Add Signature Verification Instructions

Provide instructions for users to verify release authenticity.

• Add verification instructions using sigstore verify CLI or pip install --require-hashes
• Document how to verify PyPI attestations via python -m pip download --require-attestation
• Include instructions for verifying GitHub Release signatures using sigstore verify identity
• Reference the expected signing identity (the GitHub Actions workflow OIDC identity)

🤖 Prompt for AI agents

Update `RELEASE.md` to document the new cryptographic signing process introduced
in Phase 1. The goal is to inform users and maintainers about how releases are
signed and how to verify them.

**1. Add a section on release signing:**
- Explain that releases are now cryptographically signed using Sigstore
- Note that both PyPI attestations and GitHub Release signatures are generated
- Describe the produced artifacts: `.sigstore.json` bundles containing
signature, certificate, and Rekor transparency log proof

**2. Add a signature verification instructions section:**
- Provide instructions for verifying using the `sigstore verify` CLI
- Document PyPI attestation verification via `python -m pip download
--require-attestation`
- Include instructions for verifying GitHub Release signatures using `sigstore
verify identity`
- Reference the expected signing identity (the GitHub Actions workflow OIDC
identity)

Research

The hiero-sdk-python project uses a PDM-based build system with version derived from git tags via setuptools_scm. The publish workflow (.github/workflows/publish.yml) triggers on v*.*.* tags, builds wheel and sdist artifacts, and publishes to PyPI using OIDC Trusted Publishing via pypa/gh-action-pypi-publish. The codebase follows security best practices: all actions are SHA-pinned, step-security/harden-runner is applied to every workflow, and OIDC is used instead of stored secrets. No signing or attestation is currently implemented, and no GitHub Releases are created.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Enhance `.github/workflows/publish.yml` to add cryptographic signing of release
artifacts and creation of a GitHub Release. The goal is to enable PyPI
attestations, sign artifacts with Sigstore, and attach signed artifacts to a new
GitHub Release.

**1. Update job-level permissions on the `build-and-publish` job:**
- Add `attestations: write` (for PyPI attestation generation)
- Add `contents: write` (for creating GitHub Releases and uploading assets)
- Retain the existing `id-token: write` permission
- Keep workflow-level `contents: read` as the restrictive default

**2. Enable PyPI attestations:**
- In the existing `pypa/gh-action-pypi-publish` step, add the parameter
`attestations: true`

**3. Add an artifact signing step:**
- Insert a new step using `sigstore/gh-action-sigstore-python`, placed **after**
the build step and **before** the PyPI publish step
- Configure it to sign all files in the `dist/` directory (both wheel and sdist)
- Pin the action to a full SHA hash, with a version comment, following existing
codebase conventions
- This step produces `.sigstore.json` bundle files alongside each artifact

**4. Add a GitHub Release creation step:**
- Add a new final step using `softprops/action-gh-release` (or equivalent),
pinned to a full SHA hash with a version comment
- Upload all contents of `dist/*`, including original artifacts (`.whl`,
`.tar.gz`) and signature bundles (`.sigstore.json`)
- Use the triggering tag name as the release name
- Optionally enable draft mode for manual review (configurable)

**5. Maintain security hardening:**
- Ensure `step-security/harden-runner` remains the first step in the job
- Confirm all newly added actions are pinned to full SHA hashes with version
comments
- Confirm `egress-policy: audit` is still present
===============================================================================

Task: 2

Update `RELEASE.md` to document the new cryptographic signing process introduced
in Phase 1. The goal is to inform users and maintainers about how releases are
signed and how to verify them.

**1. Add a section on release signing:**
- Explain that releases are now cryptographically signed using Sigstore
- Note that both PyPI attestations and GitHub Release signatures are generated
- Describe the produced artifacts: `.sigstore.json` bundles containing
signature, certificate, and Rekor transparency log proof

**2. Add a signature verification instructions section:**
- Provide instructions for verifying using the `sigstore verify` CLI
- Document PyPI attestation verification via `python -m pip download
--require-attestation`
- Include instructions for verifying GitHub Release signatures using `sigstore
verify identity`
- Reference the expected signing identity (the GitHub Actions workflow OIDC
identity)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[danielmarv]

/assign

[github-actions]

Hi @danielmarv, this is the Assignment Bot.

Assigning you to this issue would exceed the limit of 2 open assignments.

Please resolve and merge your existing assigned issues before requesting new ones.