diff --git a/README.md b/README.md index 635f944..e460845 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,13 @@ maintenance text belongs in package names and provenance metadata, not in a new version tag. Existing published tags remain immutable historical records; see the [release standard](docs/REPOSITORY_STANDARD.md#7-releases-and-packages). +Maintained release packages use SHA256 for archive and installer payload +integrity. The [package compatibility requirements](docs/REPOSITORY_STANDARD.md#package-integrity-and-producerconsumer-compatibility) +also cover inherited Server assets, real consumer verification and fresh-host +registration when that chain changes. Legacy SHA1 metadata is not a fallback +for current installers. These documented requirements are not a claim that every +repository's CI already enforces them. + GitHub applies supported community health files from this repository only when a target repository does not provide its own file of the same type. Repository-specific guidance always takes precedence. ## Important limitations diff --git a/docs/REPOSITORY_STANDARD.md b/docs/REPOSITORY_STANDARD.md index 0f6f6da..9a91afd 100644 --- a/docs/REPOSITORY_STANDARD.md +++ b/docs/REPOSITORY_STANDARD.md @@ -88,7 +88,7 @@ Recommended: Required for maintained releases: - identify the source commit and build inputs; -- publish checksums for downloadable artifacts; +- publish SHA256 checksums for downloadable artifacts; - document image names, tags, and digests; - use only `vMAJOR.MINOR.PATCH` or `MAJOR.MINOR.PATCH` for every new PastureStack-owned Git tag, GitHub Release, package version, and image tag; @@ -106,6 +106,42 @@ Required for maintained releases: Package and container publication remains disabled until the repository has an approved release workflow and ownership policy. +### Package integrity and producer/consumer compatibility + +Required when maintaining a release package or changing its installer contract: + +- Use SHA256 for both the outer archive and the payload integrity checks consumed + by the installer. A valid outer digest does not prove the contents satisfy the + installer contract, and checksums do not replace trusted release provenance. +- Packages consumed by the shared host installer must contain a single package + root with `SHA256SUMS` and `SHA256SUMSSUM`. Verify the payload and manifest with + the consumer's exact path and working-directory semantics, using safe extraction + confined to the isolated package root. SHA256 values are 64 hexadecimal digits. +- Current installers must reject missing, malformed or mismatching SHA256 data; + never fall back to SHA1 or MD5. Legacy SHA1 manifests may be additional metadata + only for documented older consumers; they do not satisfy current acceptance. + This does not require rewriting Git object identifiers or immutable history. +- Trace the actual producer release through Server's final image, inherited + archives, advertised download endpoint and consumer verifier. Updating source + packaging alone does not update a pinned or inherited release asset. Keep the + affected README, compatibility notes and release coordinates aligned. +- Test the final candidate archive with the actual consumer verifier: accept the + valid package; reject missing manifests, SHA1-only metadata, invalid manifests + and modified payloads. Source markers, filename checks, reconstructed fixtures + and outer checksums alone are not sufficient evidence. +- Changes to this chain, or a confirmed gap in it, require download, installation + and registration in an isolated fresh-host environment without an existing + package cache. Existing-host workloads, `/ping` and unrelated feature tests do + not prove registration. Check direct sibling packages sharing that verifier; + do not rerun registration for unrelated text or layout changes. +- Publish corrected bytes under a new numeric version; never replace a published + asset or ask operators to manufacture missing checksum files. Record a known + incompatibility as unresolved even when other feature tests passed. + +The machine-readable policy records these requirements, but does not itself +install or enforce a CI check. Automatic enforcement must be verified in each +affected release workflow before being claimed. + ## 8. Migration acceptance A repository is accepted only when the [migration checklist](MIGRATION_CHECKLIST.md) is complete and evidence is linked from a migration issue. Exceptions must identify the owner, risk, and follow-up deadline. diff --git a/standards/repository.yml b/standards/repository.yml index d7ada1d..f201862 100644 --- a/standards/repository.yml +++ b/standards/repository.yml @@ -65,5 +65,22 @@ release: regex: '^v?[0-9]+\.[0-9]+\.[0-9]+$' reuse_upstream_tags_for_rebuilds: false checksums_required: true + checksum_algorithm: sha256 + package_integrity: + outer_archive_and_inner_payload_are_separate: true + current_consumer_legacy_fallback_allowed: false + legacy_sha1_metadata: documented-older-consumers-only + shared_host_installer_manifests: + - SHA256SUMS + - SHA256SUMSSUM + final_candidate_consumer_verification_required: true + inherited_and_downloaded_assets_in_scope: true + negative_cases: + - missing-manifest + - sha1-only + - invalid-manifest + - modified-payload + fresh_registration_required_when: package-installer-chain-changed-or-gap-confirmed + documentation_is_not_ci_enforcement: true source_commit_required: true compatibility_notes_required: true