Manifest signing for the module catalog
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 0
- Forks
- 3
- Avg merge
- 8h 43m
- Merged PRs (30d)
- 60
Description
Recorded as a tracked follow-up by #72, so that removing publisher signing from the distribution design reads as a deferral with an owner rather than an omission. See docs/architecture.md section 15, cross-linked from section 9.2 and from docs/reference/module-catalog.md.
The gap
The catalog is a generated static manifest served over HTTPS, and its artifacts are unsigned. Integrity rests on SHA-256 digests plus HTTPS, which means the shell can prove that an archive it downloaded matches the entry the catalog published — and nothing more. A digest does not prove the catalog entry is authentic. Whoever can publish to the catalog origin controls the update channel for the shell and for every module, and can serve a manifest naming an artifact of their choosing along with its correct digest.
This exposure is not new: it already existed for install.sh, which is served from the same origin. What changed in #65 is the blast radius, because the same origin now carries the module catalog too. The design accepted that trade deliberately, dropping the publisher registry, per-publisher signing keys, and the TUF-style metadata hierarchy that the original architecture sketched, on the grounds that a single repository with one CODEOWNERS file does not need to answer "is this publisher authorized for this namespace?".
Dropping publisher authority is defensible on those grounds. Dropping manifest authenticity is a separate question, and this issue is the record that it was deferred rather than decided.
Current mitigation, stated at its real strength
Branch protection plus required review on the release and Pages workflows. That is a process control, not a cryptographic one: it raises the cost of an unauthorized publish and leaves an audit trail, but it does not let a client detect a forged manifest. It is also a repository setting rather than a file, so nothing in the checkout can prove it is switched on — docs/architecture.md section 9.2 says so explicitly.
Section 9.1 names the three threats the current design does not defend against: a forged catalog, rollback and freeze, and unauthorized publication.
What a decision here needs to weigh
- Whether to sign the two catalog documents, the per-release artifacts, or both.
- Where a verifying key lives and how it reaches the shell. A key shipped in the shell binary and fetched from the same origin it protects buys very little.
- Key custody and rotation, and what the shell does when it meets a manifest signed by a key it does not know.
- Rollback and freeze protection, which signing alone does not give — this needs monotonic metadata such as a version or an expiry, not just a signature.
- Whether existing platform machinery (Sigstore, GitHub attestations) covers enough of this to avoid custom key handling.
- What the shell does on a verification failure, following the existing refusal idiom: distinguishable problem codes and exit classes, never a generic failure.
Out of scope
Restoring the publisher registry, per-publisher signing keys, delegated namespace publishing authority, or revocation. #65 dropped those deliberately and this issue does not reopen them. The question here is narrower: can a client tell that the manifest it fetched is the one this project published?
Needs an owner
This issue exists so the deferral has one. It is unassigned, and assigning it is the remaining step.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/architecture.md sections 9.1, 9.2, and 15, then read docs/reference/module-catalog.md and the linked issues #65 and #72. Compare the signing, key distribution, rollback, and failure-handling questions, and record a concrete decision and owner without reopening publisher authority or revocation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100