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

Merged

james merged 1 commit from 83-cosign-pub-public-docs into main 2026-06-17 21:50:01 +00:00

Conversation 0 Commits 1 Files changed 2 +62 -5

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

Owner

Copy link

Closes #83.

Summary

Documentation cleanup capturing the actual root cause that #81 / #82 chased: the "no known key found for this signature in database" symptom was repo-visibility, not anything cosign was doing wrong.

What changed in docs/ci.md "Release pipeline"

1. Prerequisite callout under "Verifying a published image": the cosign.pub URL must return the raw PEM to an unauthenticated GET. Either the repo is public, or cosign.pub is republished from a separate world-readable location.
2. Clarification of the "verified offline" line. cosign emits "Existence of the claims in the transparency log was verified offline" on success, which initially looked like Rekor was being bypassed. It's actually the intended fast path — cosign embeds Rekor's SignedEntryTimestamp into the signature bundle at sign time and validates it against Sigstore's well-known Rekor public key at verify time, without a network call. Same cryptographic guarantee.
3. New "Troubleshooting verification" section that names the "no known key found" error and lists the actual likely causes (visibility, URL typo, predates current keypair), plus the one-liner local-file bypass diagnostic.

What changed in ADR-0014

A new negative-consequence bullet capturing the repo-visibility coupling: the release-notes verify command assumes anonymous reachability of cosign.pub. Points at the new troubleshooting section.

Acceptance criteria

• docs/ci.md has the prerequisite callout under "Verifying a published image".
• docs/ci.md has a Troubleshooting section for the "no known key" symptom.
• ADR-0014 mentions the anonymous-fetchability assumption.
• Closed issues #81 and #82 get a short comment with the actual root cause for future readers. (Will post these as PR comments after this merges so the cross-references resolve cleanly.)

Why not also fix #82's stated cause?

PR #82's --tlog-upload=true change was still correct — sigs are now genuinely in Rekor (logIndex: 1854384861 confirmed on the rc.2 sign step output), and cosign verify reports Existence of the claims in the transparency log was verified offline against the embedded proof. That fix earns its keep; we just attributed the user-visible symptom to it incorrectly. This PR leaves #82 alone and adds the missing prereq separately.

Closes #83. ## Summary Documentation cleanup capturing the actual root cause that #81 / #82 chased: the "no known key found for this signature in database" symptom was repo-visibility, not anything cosign was doing wrong. ### What changed in `docs/ci.md` "Release pipeline" 1. **Prerequisite callout** under "Verifying a published image": the `cosign.pub` URL must return the raw PEM to an unauthenticated GET. Either the repo is public, or `cosign.pub` is republished from a separate world-readable location. 2. **Clarification of the "verified offline" line.** cosign emits "Existence of the claims in the transparency log was verified offline" on success, which initially looked like Rekor was being bypassed. It's actually the intended fast path — cosign embeds Rekor's `SignedEntryTimestamp` into the signature bundle at sign time and validates it against Sigstore's well-known Rekor public key at verify time, without a network call. Same cryptographic guarantee. 3. **New "Troubleshooting verification" section** that names the "no known key found" error and lists the actual likely causes (visibility, URL typo, predates current keypair), plus the one-liner local-file bypass diagnostic. ### What changed in ADR-0014 A new negative-consequence bullet capturing the repo-visibility coupling: the release-notes verify command assumes anonymous reachability of `cosign.pub`. Points at the new troubleshooting section. ## Acceptance criteria - [x] `docs/ci.md` has the prerequisite callout under "Verifying a published image". - [x] `docs/ci.md` has a Troubleshooting section for the "no known key" symptom. - [x] ADR-0014 mentions the anonymous-fetchability assumption. - [ ] Closed issues #81 and #82 get a short comment with the actual root cause for future readers. *(Will post these as PR comments after this merges so the cross-references resolve cleanly.)* ## Why not also fix #82's stated cause? PR #82's `--tlog-upload=true` change was still correct — sigs are now genuinely in Rekor (`logIndex: 1854384861` confirmed on the rc.2 sign step output), and `cosign verify` reports `Existence of the claims in the transparency log was verified offline` against the embedded proof. That fix earns its keep; we just attributed the user-visible symptom to it incorrectly. This PR leaves #82 alone and adds the missing prereq separately.

james added 1 commit 2026-06-17 21:47:50 +00:00

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

The "no known key found for this signature in database" symptom chased
through #81 and #82 turned out to be repo-visibility, not anything
cosign was doing wrong: cosign's HTTP client doesn't carry a Forgejo
session, so an anonymous GET on the cosign.pub URL of a private repo
returns a login page, not the PEM. Document the prerequisite so
future-me doesn't burn the same debugging cycle.

Also clarify two adjacent confusions surfaced during the same cycle:

  - "Existence of the claims in the transparency log was verified
    offline" is the intended fast path, not a Rekor bypass. cosign
    embeds Rekor's SignedEntryTimestamp into the sig bundle at sign
    time; verify validates that embedded proof against Sigstore's
    well-known Rekor key without a network call.
  - Add a "Troubleshooting verification" section that names the
    "no known key" error and lists the actual likely causes
    (visibility, URL typo, predates current keypair), plus the
    one-liner local-file bypass for diagnosing.

ADR-0014 picks up a matching negative-consequence bullet so the
repo-visibility coupling is captured in the long-form decision log.

Closes #83.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

james referenced this pull request 2026-06-17 21:48:50 +00:00

Publish cosign signatures to Sigstore public-good Rekor #81

james referenced this pull request 2026-06-17 21:49:02 +00:00

fix(release): publish cosign sigs to Sigstore Rekor (#81) #82

james merged commit e377f81ec2 into main 2026-06-17 21:50:01 +00:00

james referenced this pull request from a commit 2026-06-17 21:50:01 +00:00

Merge pull request 'docs(release): cosign.pub URL must be anonymously fetchable + clarify verify "offline" (#83)' (#84) from 83-cosign-pub-public-docs into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!84

No description provided.