Document `cosign.pub` URL must be anonymously fetchable; clarify "verified offline" Rekor behaviour #83

New issue

Closed

opened 2026-06-17 21:07:18 +00:00 by james · 0 comments

james commented

2026-06-17 21:07:18 +00:00

Owner

Cleanup follow-up from the #81 / #82 debugging cycle.

Root-cause correction

The user-visible "no known key found for this signature in database" error chased through #81 and #82 was ultimately caused by repo visibility, not by anything cosign was doing wrong:

The repo was private at the time of debugging.
The verify command in the release notes uses --key https://forge.wynning.tech/james/carol/raw/branch/main/cosign.pub.
cosign's HTTP client doesn't carry your Forgejo session — it does an anonymous GET on that URL.
For a private repo, that GET gets a login page (HTML), not the PEM-encoded public key.
cosign can't parse the response as a key, fails the verification with the misleading "no known key" message.

The actual fixes #82 added (explicit --tlog-upload=true) were still correct — sigs are now genuinely uploaded to Rekor and verifiable — but they weren't the cause of the symptom.

Scope

Add a "Prerequisites" callout to docs/ci.md "Release pipeline" → "Verifying a published image" that says: the cosign.pub URL must return the raw PEM to an unauthenticated request. Either the repo is public, or cosign.pub is served from a separate publicly-readable location (a release asset on a public mirror repo, a static site, a public gist, etc.) and the release-notes template is adjusted to point at it.
Clarify the existing paragraph about Rekor: in practice, cosign verify reports "Existence of the claims in the transparency log was verified offline" because cosign embeds Rekor's SignedEntryTimestamp into the signature bundle at sign time, and uses that embedded proof at verify time — no live call to rekor.sigstore.dev is required. This is a property, not a bug. Document it so future-me doesn't mistake it for the verify path bypassing Rekor.
Add a one-paragraph "What if I see 'no known key found in database'?" troubleshooting entry pointing at the visibility check.
Add a sentence to ADR-0014's "Consequences" capturing the repo-visibility coupling: the verify command in the release notes assumes anonymous reachability of the cosign.pub URL.

Acceptance criteria

docs/ci.md has the prerequisite callout under "Verifying a published image".
docs/ci.md has a brief troubleshooting note for the "no known key" symptom.
ADR-0014 mentions the assumption that cosign.pub is anonymously fetchable.
Closed issues #81 and #82 get a short comment with the actual root cause for anyone reading them later.

Out of scope

Moving cosign.pub to a separate public location (not needed today since the repo is now public).
Re-attempting the rc.1 / rc.0 verifications (those releases either never had Rekor entries or are otherwise un-recoverable; forward-only).

Part of epic #2. Follow-up from #81 / #82.

Cleanup follow-up from the #81 / #82 debugging cycle. ## Root-cause correction The user-visible "no known key found for this signature in database" error chased through #81 and #82 was ultimately caused by **repo visibility**, not by anything cosign was doing wrong: 1. The repo was private at the time of debugging. 2. The verify command in the release notes uses `--key https://forge.wynning.tech/james/carol/raw/branch/main/cosign.pub`. 3. cosign's HTTP client doesn't carry your Forgejo session — it does an anonymous GET on that URL. 4. For a private repo, that GET gets a login page (HTML), not the PEM-encoded public key. 5. cosign can't parse the response as a key, fails the verification with the misleading "no known key" message. The actual fixes #82 added (explicit `--tlog-upload=true`) were still correct — sigs are now genuinely uploaded to Rekor and verifiable — but they weren't the cause of the symptom. ## Scope - Add a "Prerequisites" callout to `docs/ci.md` "Release pipeline" → "Verifying a published image" that says: **the cosign.pub URL must return the raw PEM to an unauthenticated request.** Either the repo is public, or `cosign.pub` is served from a separate publicly-readable location (a release asset on a public mirror repo, a static site, a public gist, etc.) and the release-notes template is adjusted to point at it. - Clarify the existing paragraph about Rekor: in practice, `cosign verify` reports "Existence of the claims in the transparency log was verified offline" because cosign embeds Rekor's SignedEntryTimestamp into the signature bundle at sign time, and uses that embedded proof at verify time — no live call to `rekor.sigstore.dev` is required. This is a property, not a bug. Document it so future-me doesn't mistake it for the verify path bypassing Rekor. - Add a one-paragraph "What if I see 'no known key found in database'?" troubleshooting entry pointing at the visibility check. - Add a sentence to ADR-0014's "Consequences" capturing the repo-visibility coupling: the verify command in the release notes assumes anonymous reachability of the cosign.pub URL. ## Acceptance criteria - [ ] `docs/ci.md` has the prerequisite callout under "Verifying a published image". - [ ] `docs/ci.md` has a brief troubleshooting note for the "no known key" symptom. - [ ] ADR-0014 mentions the assumption that `cosign.pub` is anonymously fetchable. - [ ] Closed issues #81 and #82 get a short comment with the actual root cause for anyone reading them later. ## Out of scope - Moving `cosign.pub` to a separate public location (not needed today since the repo is now public). - Re-attempting the rc.1 / rc.0 verifications (those releases either never had Rekor entries or are otherwise un-recoverable; forward-only). Part of epic #2. Follow-up from #81 / #82.

james referenced this issue from a commit

2026-06-17 21:43:46 +00:00

docs(release): cosign.pub URL must be anonymously fetchable + clarify verify "offline" (#83)

james added the

area:ci

label

2026-06-17 21:43:54 +00:00

james referenced this issue from a pull request that will close it,

2026-06-17 21:47:50 +00:00

docs(release): cosign.pub URL must be anonymously fetchable + clarify verify "offline" (#83) #84

james referenced this issue

2026-06-17 21:48:50 +00:00