Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Verifying a Synapse release (SYN-108)

Release signatures and checksums authenticate the bytes you download under a selected publisher identity. They complement workspace verification, which checks different properties. Neither mechanism proves general factual truth, complete supply-chain safety or freedom from defects.

The release workflow uses keyless Sigstore / cosign with short-lived signing credentials, rather than a project-maintained long-lived release key. The signing identity is the GitHub Actions release workflow (.github/workflows/release.yml on the pushed tag), and its signature evidence includes the public Rekor transparency log entry. For a release using this workflow, inspect these assets:

  • the platform archives (synapse-<version>-<target>.tar.gz / .zip),
  • SHA256SUMS: a checksum manifest over every archive,
  • SHA256SUMS.cosign.bundle: the cosign signature + certificate + Rekor entry for SHA256SUMS.

The SYN-340 release workflow additionally includes release-metadata.json in the signed manifest. It records the selected source commit, package/changelog input digests and exact release-notes digest. Validate its manifest entry before using it to compare source and notes. This is a declaration authenticated under the selected workflow identity, not independent build provenance or proof of reproducible compilation. Earlier releases can lack this receipt.

Verify (one time: install cosign)

Install cosign (brew install cosign, or the release binary from sigstore/cosign).

Verify a download

Choose a release tag and platform explicitly, then retain its SHA256SUMS, SHA256SUMS.cosign.bundle and selected archive together. Source-tree features can be newer than the binary on that tag; consult its release notes rather than inferring capabilities from this documentation. Before extraction, authenticate the checksum manifest:

# Example tag, not a request for the newest release. Select the reviewed tag you need.
SYNAPSE_RELEASE_TAG=v1.4.0

# 1. Authenticate the checksum manifest under the exact selected workflow/tag identity.
cosign verify-blob \
  --bundle SHA256SUMS.cosign.bundle \
  --certificate-identity "https://github.com/romulofebasi/synapse/.github/workflows/release.yml@refs/tags/${SYNAPSE_RELEASE_TAG}" \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  SHA256SUMS
# → "Verified OK"

# 2. Compare downloaded archives against the authenticated manifest (GNU sha256sum).
sha256sum --check --ignore-missing SHA256SUMS
# → synapse-<version>-<target>.tar.gz: OK

Both checks must pass for the specific archive you intend to extract. Confirm that it is present, has a matching manifest entry and reports OK; a successful check of another file is insufficient. On macOS, shasum -a 256 <archive> prints the digest for exact comparison with its authenticated entry. Replace the placeholder with the actual filename. An absent bundle, unexpected identity, unsupported verification format or failed check stops this manual workflow. A valid signature remains valid when identical assets are mirrored; it is an unexpected signing identity or changed bytes that the checks reject.

What this proves (and does not)

  • Establishes: the manifest verifies under the selected tagged workflow identity and issuer, and the selected archive matches a digest in that authenticated manifest.
  • Does not establish: bug-free source, operating-system signing/notarization, exhaustive build provenance, workspace integrity or the truth of stored claims. Retained bundle verification depends on the cosign version, trusted roots and verification policy.

syn verify separately reports named properties of a selected workspace, with prerequisites, exclusions and skipped checks. A successful report is not a universal proof that no silent alteration ever occurred. See the verification scope.

Convenience installer behavior

The public installer is best-effort. It compares the archive checksum when the manifest, matching entry and local hash utility are available, and a detected mismatch stops installation. A missing manifest warns and continues; a missing entry or hash utility can skip comparison.

When cosign and the bundle are available, it attempts signature verification. A signature failure warns and continues on the checksum path; unavailable cosign or bundle can skip the signature check. Pinning SYNAPSE_VERSION chooses the requested tag but does not make these checks mandatory. Use the explicit manual workflow above when both checks are required. This guide does not change the installer or imply that Gatekeeper/SmartScreen trust is supplied by Sigstore signing.

Release preparation and mirror limits

The prepared SYN-340 pipeline consumes a committed version and generated changelog from an exact existing tag. It pins every platform build to that commit, uses the locked graph and refuses an incomplete four-platform inventory. It creates no source commits and writes no source branch. The mirror compares the original tag/source receipt, notes, asset hashes and tagged workflow signature, then copies the same bytes and bundle. The mirror tag is a distribution reference; it does not establish that the public mirror contains the private source commit.

Both publication paths refuse an existing release, including an identical rerun, and stop when API errors prevent verifying absence. They contain no automatic delete/replace recovery. This protects the normal workflow from accidental replacement; administrators can still alter GitHub objects. A partial failed publication needs owner inspection. See ADR-007 and the 1.5.0 preparation record. Preparation alone creates no tag, archive, verified signature or released capability.

Canonical documentation in forward releases

Starting with the SYN-343 producer correction, source publication checks the full changelog inside every platform archive against the exact committed-source receipt before creating the checksum manifest or invoking Sigstore. Packaging reads README.md, LICENSE and CHANGELOG.md from Git blobs, including on Windows. This correction shipped in v1.5.1. The actual publication verification checks the signed source and mirror artifacts, raw documents in all four archives, five npm packages and the host launcher. Previously published v1.5.0 artifacts are outside this forward correction. Downstream verification remains strict. See the producer evidence and remaining limits.

The separate retained-evidence review recomputes inventory, document, SRI and binary agreement and records reviewer roles.