release(installer): verify published checksums and expose fail-closed provenance mode

[Rul1an]

Parent: #1975

Measured gap

Measured on origin/main 7f5a811f750f36974d307688dd60f8b710824543 and published release v5.5.2.

The fast path in README.md is:

curl -fsSL https://getassay.dev/install.sh | sh

The same page correctly discloses that this installer downloads over HTTPS but does not consume the release's checksum or provenance sidecars. v5.5.2 publishes a .sha256 beside every CLI archive and also publishes assay-v5.5.2-release-provenance.json plus its checksum.

This leaves the release process stronger than the default installation path: Assay produces integrity/provenance evidence that the fast path does not verify.

Contract

1. The selected release version, target triple and archive name are resolved once and reused for archive, checksum and diagnostics.
2. The installer downloads the archive and its exact .sha256 sidecar before extraction.
3. Archive verification is mandatory and fail-closed. A missing, malformed or mismatching sidecar must leave the destination binary unchanged.
4. Use the platform's supported SHA-256 implementation (sha256sum or shasum -a 256) without weakening the digest comparison.
5. Add an explicit provenance-verification mode. If that mode is required, missing verification tooling or a signer/workflow mismatch is a failure, never a checksum-only pass wearing an attestation label.
6. Output distinguishes checksum_verified, provenance_verified, provenance_not_requested and failure. HTTPS transport alone is never called provenance verification.
7. A verified temporary archive is activated atomically; a failed install preserves the prior binary.

RED-first cases

• correct archive + correct sidecar succeeds;
• archive byte changed after sidecar publication refuses before extraction;
• missing or malformed sidecar refuses;
• sidecar for a different asset refuses;
• required provenance with missing verifier refuses;
• required provenance with wrong repository/workflow identity refuses;
• failed verification preserves an already installed binary;
• the output cannot report provenance_verified on the checksum-only path.

Definition of done

• Linux and macOS fast paths verify the exact selected archive checksum.
• One supported, fail-closed provenance-verification path is documented and tested.
• The installer and README no longer contain two separately maintained version or asset-selection rules.
• The published-artifact smoke installs through this exact path.
• README wording states precisely what the default and strict modes verify.
• No new release is claimed until the changed installer is deployed and measured against a published release.

Non-claims

• A checksum proves byte equality with the sidecar, not who produced it.
• A verified provenance document does not prove runtime safety or semantic correctness.
• This does not package the bounded quickstart assets; that remains separate product work.

Basis

• Existing productization contract: Productization: ship an install-to-verified-evidence golden path #1975.
• Current public disclosure: README.md:49-51 at the measured SHA.
• Product benchmark: Pipelock's quickstart verifies release attestations rather than leaving release evidence unused.

[Rul1an]

2026-09-02 implementation disposition

Independent read-only design plus primary-source recheck, pinned to:

• Assay 7f5a811f750f36974d307688dd60f8b710824543;
• getassay-site 091b124ebdb090232f6360e924b07a4e5b9eb329;
• published v5.5.2 / source digest d813af0e52f2846d3e5f47a53c042aa169304dc3;
• live installer SHA-256 bb23a411d8a48c0adda27e6aeb9d3d02c4c3eea8ebad463545578c3be8e3ab2f.

Assay and site currently carry the same installer blob 6131fc97415d6e626ba0c63d29754645df826e21. The site checker explicitly says Assay authors the installer and the site republishes it. Keep that ownership.

Two-PR sequence

1. Assay canonical behavior

   • change scripts/install.sh;
   • add a dedicated whole-installer release-verification suite instead of enlarging the existing version-normalization suite;
   • wire Linux and macOS native SHA paths;
   • update source documentation only to describe the canonical contract, not claim that production deployment already changed.

2. getassay-site deployment and live proof

   • copy the exact merged Assay installer bytes;
   • update the site provenance pin to the merged Assay commit/digest;
   • preserve the existing byte/provenance checker;
   • make the production smoke execute https://getassay.dev/install.sh into a disposable prefix;
   • verify live digest, selected v5.5.2 asset and installed version after Cloudflare deployment.

No separate site implementation of installer rules.

Strict provenance correction

The strict mode's trust root is the downloaded archive attestation, not release-provenance.json. The latter and the proof kit are intentionally derived after archive attestations and are expected to have no attestation themselves.

A live verification of the v5.5.2 Linux archive established:

• archive SHA-256 f7cd1046a7b09808baf6fdd590464edc968de2c0dab7bbc4efacb33b6ca25292;
• repository/workflow/OIDC/SLSA/self-hosted restrictions plus --source-digest d813af0e...: PASS;
• the same command with --source-ref refs/tags/v5.5.2: FAIL, because the attestation records refs/heads/main.

Therefore strict mode must resolve the selected release tag to its commit and bind gh attestation verify --source-digest <tag-peel>. It must not claim that the attestation's source ref is the tag.

Small implementation shape

Use one resolver for version/target/archive/sidecar URL, one SHA implementation selector, one exact sidecar verifier, one strict attestation verifier and one same-directory activation function. Verify checksum, then optional required provenance, then extract, then stage inside the install directory, chmod the staged file and rename it over the destination. Every earlier failure preserves the old binary.

Required output states remain distinct:

• checksum_verified;
• provenance_not_requested;
• provenance_verified;
• named checksum/provenance/activation failure.

Release disposition

This does not require republishing immutable v5.5.2 assets or cutting a new Assay binary release. The implementation and site-deployment commits must be independently reviewed and the changed live installer measured against v5.5.2. A future Assay release may advertise the improved installer, but no shipped-state sentence is valid before the site deployment proof.

Non-claims remain: no generic updater, package manager, provider abstraction, transactional config rollback, Windows replacement guarantee, or safety/certification claim.

[Rul1an]

Published checksum format pinned

Verified directly against the non-draft, non-prerelease v5.5.2 release at source d813af0e52f2846d3e5f47a53c042aa169304dc3.

The Linux CLI sidecar is one 110-byte line:

f7cd1046a7b09808baf6fdd590464edc968de2c0dab7bbc4efacb33b6ca25292  assay-v5.5.2-x86_64-unknown-linux-gnu.tar.gz

The installer contract should therefore parse exactly one line containing 64 lowercase hexadecimal characters, two spaces, and the exact expected archive basename. It must not accept a digest-only line, an absolute/path-bearing filename, extra records, or a sidecar naming a different asset. The computed archive digest is then compared before extraction or activation.

This pins the currently published producer shape; it is not a claim that arbitrary checksum-file formats are supported.

[Rul1an]

Provenance policy boundary and parity requirement

Primary-source check against the current GitHub CLI contract:

• gh attestation verify checks the local artifact's integrity plus a signed provenance claim and permits explicit repository, signer-workflow, OIDC issuer, predicate type, source digest and self-hosted-runner restrictions.
• GitHub explicitly warns that an attestation links an artifact to source/build identity; it does not establish that the artifact is safe.
• Predicate contents are workflow-controlled. The certificate identity and verified timestamps are the non-workflow-controlled parts, so strict mode must enforce builder identity rather than parse a convenient predicate field as authority.

References:

• https://cli.github.com/manual/gh_attestation_verify
• https://docs.github.com/en/actions/concepts/security/artifact-attestations

Assay already encodes the release policy in scripts/ci/release_attestation_enforce.sh. The installer cannot directly reuse that multi-asset CI driver because it requires the repository checkout, inventory machinery and retained JSON outputs. Therefore the fallback required by AGENTS.md is an explicit parity test, not a second unguarded policy:

• installer strict-mode argv and the CI verifier must agree on repository, signer workflow, OIDC issuer, SLSA predicate, source digest and deny-self-hosted-runners;
• removing any one binding from either side must make the parity/behavior test RED;
• checksum-only mode reports provenance_not_requested, never a weaker provenance_verified;
• strict success reports both checksum and attestation verification as separate facts.

Do not substitute gh release verify-asset without a separately reviewed contract change: release-attestation verification and Assay's current build-workflow/source-digest policy are adjacent but not identical properties.

[Rul1an]

Interface decision and verified adjacent false-green

This supersedes the earlier suggested ASSAY_PROVENANCE_MODE enum.

Public opt-in

Use one minimal public selector:

• unset: mandatory checksum verification, provenance_not_requested;
• ASSAY_REQUIRE_PROVENANCE=1: checksum plus required provenance verification;
• any other set value, including empty or 0: refuse before network access.

There is no demonstrated need for multiple provenance modes in the installer. A closed boolean opt-in is smaller and keeps future offline-bundle or provider choices out of this slice.

Existing attestation-test gap

Direct source verification on Assay main 7f5a811 confirmed:

• production release_attestation_enforce.sh passes repository, signer workflow, OIDC issuer, predicate type, source digest and deny-self-hosted-runners;
• test-release-attestation-enforce.sh asserts signer workflow, source digest and deny-self-hosted-runners, but does not assert repository, OIDC issuer or predicate type;
• its fake gh accepts success without validating those omitted bindings.

This is an existing false-green on the same policy #2749 must reuse. Include scripts/ci/test-release-attestation-enforce.sh in the slice and add behavior/mutations for all six bindings. Removing repository, OIDC issuer or predicate type from production must turn the test RED. The new installer parity test must then compare against a policy whose own tests actually bite.

Do not split this into a generic attestation framework. It is one bounded repair to the existing release policy plus the installer consumer.

[Rul1an]

Pipelock benchmark boundary

Current primary-source comparison: https://github.com/luckyPipewrench/pipelock

Pipelock exposes a verified self-update path with a signed release manifest, selected-asset checksum verification, optional cosign cross-check, atomic install and rollback. Assay #2749 should match the relevant control quality, not copy that product surface:

• selected archive bytes are verified before extraction;
• strict opt-in binds archive provenance to the expected source/build identity;
• activation is one same-directory replacement after every check;
• any failure preserves the previously installed binary;
• output says which property was and was not verified.

Deliberate MVP differences:

• Assay verifies GitHub artifact attestation rather than introducing a second signed release-manifest trust root;
• this remains an installer, not a self-update command;
• preservation on failed activation is required, but post-success version rollback is not added;
• cosign/provider abstraction and package-manager updates remain outside scope.

Therefore a clean #2749 result reaches the relevant Pipelock-level installer integrity boundary without claiming Pipelock's updater lifecycle.