From 68a3c7eb1322e276f77796f9d31d1760c1626462 Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:07:47 +1000 Subject: [PATCH 1/6] docs: how to verify a download against the checksums file The site told people how to install Ahoy but never how to check what they had downloaded, even though every release ships a checksums file. Notes that the raw ahoy-bin-* binaries are only covered from v3.0.1. In v3.0.0 and earlier the file listed the archives and SBOMs only, so the binary the documented install command fetches was the one artifact that could not be verified. Both commands were run against the live v3.0.1 release: a clean download reports OK, and a corrupted one reports FAILED. Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d --- src/content/docs/guides/getting-started.mdx | 26 +++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index bd5f2d8..53ce0d9 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -49,6 +49,32 @@ Verify it's working: ahoy --version ``` +## Verifying your download + +Every release ships an `ahoy__checksums.txt` listing a SHA-256 for each +published file, so you can confirm a download arrived intact. + +```bash +VERSION=3.0.1 +BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION + +curl -fsSLO $BASE/ahoy-bin-linux-amd64 +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt + +sha256sum -c ahoy_${VERSION}_checksums.txt --ignore-missing +``` + +`--ignore-missing` checks only the files you actually downloaded, rather than +complaining about the thirty or so you did not. On macOS, use +`shasum -a 256 -c` in place of `sha256sum -c`. + + + ## Start with examples The quickest way to get going is to initialise a project with our curated examples file. It includes 30+ ready-to-use commands for common development workflows. From d9b2dc11258c65e0a616df644f5fa6065ab86071 Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:08:38 +1000 Subject: [PATCH 2/6] docs: how to verify a release signature with cosign Companion to the cosign signing added in ahoy-cli/ahoy. Explains what a signature adds over a checksum, and gives the verify-blob invocation with the workflow identity to assert. Two things worth stating explicitly, because both are easy to get wrong: signing is keyless so there is no public key to fetch, and cosign v3 replaced --output-signature and --output-certificate with --bundle, so examples written for v2 do not work. The version in the example is a placeholder for the first signed release and needs confirming before this merges, as does the exact certificate-identity-regexp, which can only be read off a real signed run. Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d --- src/content/docs/guides/getting-started.mdx | 35 +++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index 53ce0d9..c094773 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -75,6 +75,41 @@ complaining about the thirty or so you did not. On macOS, use be verified. +### Checking the signature + +Checksums prove a file arrived intact, but not who produced it: anyone able to +replace a binary could replace the checksums file alongside it. Releases are +therefore signed with [cosign](https://docs.sigstore.dev/), and the signature +covers the checksums file, which in turn covers every other artifact. + +Signing is keyless, so there is no public key to fetch. The signature records +the GitHub Actions workflow that built the release, and you assert which +identity you expect: + +```bash +VERSION=3.0.2 +BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION + +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt.bundle + +cosign verify-blob ahoy_${VERSION}_checksums.txt \ + --bundle ahoy_${VERSION}_checksums.txt.bundle \ + --certificate-identity-regexp '^https://github.com/ahoy-cli/ahoy/\.github/workflows/release\.yml@' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` + +`Verified OK` means the checksums file was produced by Ahoy's own release +workflow. Check the artifacts against it as above, and the whole download is +accounted for. + + + ## Start with examples The quickest way to get going is to initialise a project with our curated examples file. It includes 30+ ready-to-use commands for common development workflows. From c47b5527e5d52a328dd29603eadba718159d8e82 Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:14:49 +1000 Subject: [PATCH 3/6] docs: fix the anchor link to the verification section The link rendered as literal text rather than a link. Two problems: the destination contained unescaped spaces, which stops markdown parsing it as a link at all, and the anchor did not match the generated id. Starlight slugifies headings, so 'Verifying your download' becomes #verifying-your-download, lowercase, hyphenated and singular. Checked against the built HTML, and swept every in-page anchor on the site to confirm they all resolve to a real id. Claude-Session: https://claude.ai/code/session_01629NFuQxTr678Tdh8AD39d --- src/content/docs/guides/getting-started.mdx | 126 ++++++++++---------- 1 file changed, 64 insertions(+), 62 deletions(-) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index c094773..fa8c4b5 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -9,7 +9,7 @@ import { Aside } from "@astrojs/starlight/components"; ## Installation - + ```bash brew install ahoy ``` @@ -43,73 +43,14 @@ import { Aside } from "@astrojs/starlight/components"; ``` +For security's sake, please [verify your download](#verifying-your-download). + Verify it's working: ```bash ahoy --version ``` -## Verifying your download - -Every release ships an `ahoy__checksums.txt` listing a SHA-256 for each -published file, so you can confirm a download arrived intact. - -```bash -VERSION=3.0.1 -BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION - -curl -fsSLO $BASE/ahoy-bin-linux-amd64 -curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt - -sha256sum -c ahoy_${VERSION}_checksums.txt --ignore-missing -``` - -`--ignore-missing` checks only the files you actually downloaded, rather than -complaining about the thirty or so you did not. On macOS, use -`shasum -a 256 -c` in place of `sha256sum -c`. - - - -### Checking the signature - -Checksums prove a file arrived intact, but not who produced it: anyone able to -replace a binary could replace the checksums file alongside it. Releases are -therefore signed with [cosign](https://docs.sigstore.dev/), and the signature -covers the checksums file, which in turn covers every other artifact. - -Signing is keyless, so there is no public key to fetch. The signature records -the GitHub Actions workflow that built the release, and you assert which -identity you expect: - -```bash -VERSION=3.0.2 -BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION - -curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt -curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt.bundle - -cosign verify-blob ahoy_${VERSION}_checksums.txt \ - --bundle ahoy_${VERSION}_checksums.txt.bundle \ - --certificate-identity-regexp '^https://github.com/ahoy-cli/ahoy/\.github/workflows/release\.yml@' \ - --certificate-oidc-issuer https://token.actions.githubusercontent.com -``` - -`Verified OK` means the checksums file was produced by Ahoy's own release -workflow. Check the artifacts against it as above, and the whole download is -accounted for. - - - ## Start with examples The quickest way to get going is to initialise a project with our curated examples file. It includes 30+ ready-to-use commands for common development workflows. @@ -172,3 +113,64 @@ ahoy # Shows all commands and their usage text - [Shell Autocompletion](/guides/shell-autocompletion) - set up tab completion - [YAML Schema Reference](/reference/yaml-schema) - complete field-by-field reference - [CLI Reference](/reference/cli) - all command-line flags and built-in commands + +## Verifying your download + +Every release ships an `ahoy__checksums.txt` listing a SHA-256 for each +published file, so you can confirm a download arrived intact. + +```bash +VERSION=3.0.1 +BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION + +curl -fsSLO $BASE/ahoy-bin-linux-amd64 +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt + +sha256sum -c ahoy_${VERSION}_checksums.txt --ignore-missing +``` + +`--ignore-missing` checks only the files you actually downloaded, rather than +complaining about the thirty or so you did not. On macOS, use +`shasum -a 256 -c` in place of `sha256sum -c`. + + + +### Checking the signature + +Checksums prove a file arrived intact, but not who produced it: anyone able to +replace a binary could replace the checksums file alongside it. Releases are +therefore signed with [cosign](https://docs.sigstore.dev/), and the signature +covers the checksums file, which in turn covers every other artifact. + +Signing is keyless, so there is no public key to fetch. The signature records +the GitHub Actions workflow that built the release, and you assert which +identity you expect: + +```bash +VERSION=3.0.2 +BASE=https://github.com/ahoy-cli/ahoy/releases/download/v$VERSION + +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt +curl -fsSLO $BASE/ahoy_${VERSION}_checksums.txt.bundle + +cosign verify-blob ahoy_${VERSION}_checksums.txt \ + --bundle ahoy_${VERSION}_checksums.txt.bundle \ + --certificate-identity-regexp '^https://github.com/ahoy-cli/ahoy/\.github/workflows/release\.yml@' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com +``` + +`Verified OK` means the checksums file was produced by Ahoy's own release +workflow. Check the artifacts against it as above, and the whole download is +accounted for. + + From cbd9a2c346ae81bdd00027fae56659eb46c4694c Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:19:14 +1000 Subject: [PATCH 4/6] Tweak docs --- src/content/docs/guides/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index fa8c4b5..438730e 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -45,7 +45,7 @@ import { Aside } from "@astrojs/starlight/components"; For security's sake, please [verify your download](#verifying-your-download). -Verify it's working: +Then verify that `ahoy` is working: ```bash ahoy --version From 65a86249da41663c3123d958db2ce33ab79ebc4d Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:19:38 +1000 Subject: [PATCH 5/6] Tweak docs --- src/content/docs/guides/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index 438730e..cb4ccf4 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -53,7 +53,7 @@ ahoy --version ## Start with examples -The quickest way to get going is to initialise a project with our curated examples file. It includes 30+ ready-to-use commands for common development workflows. +The quickest way to get going is to initialise a project with our curated examples file. It includes 20+ ready-to-use commands for common development workflows. ```bash cd my-project From 046d3c90c8330136b9a340e24ce898d179046289 Mon Sep 17 00:00:00 2001 From: Drew Robinson Date: Thu, 3 Sep 2026 14:21:25 +1000 Subject: [PATCH 6/6] Adjust page layout --- src/content/docs/guides/getting-started.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/guides/getting-started.mdx b/src/content/docs/guides/getting-started.mdx index cb4ccf4..7cdbb00 100644 --- a/src/content/docs/guides/getting-started.mdx +++ b/src/content/docs/guides/getting-started.mdx @@ -107,13 +107,6 @@ ahoy # Shows all commands and their usage text in your project. -## Next steps - -- [Writing Commands](/guides/writing-commands) - practical patterns and real-world examples -- [Shell Autocompletion](/guides/shell-autocompletion) - set up tab completion -- [YAML Schema Reference](/reference/yaml-schema) - complete field-by-field reference -- [CLI Reference](/reference/cli) - all command-line flags and built-in commands - ## Verifying your download Every release ships an `ahoy__checksums.txt` listing a SHA-256 for each @@ -174,3 +167,10 @@ accounted for. `--output-signature` and `--output-certificate` flags with `--bundle`, so examples written for cosign v2 will not work. + +## Next steps + +- [Writing Commands](/guides/writing-commands) - practical patterns and real-world examples +- [Shell Autocompletion](/guides/shell-autocompletion) - set up tab completion +- [YAML Schema Reference](/reference/yaml-schema) - complete field-by-field reference +- [CLI Reference](/reference/cli) - all command-line flags and built-in commands