From d96a756842f436bfd14b24e61b3e4ba09f3c6d4c Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:48:07 -0500 Subject: [PATCH 1/3] ci(release): sign releases with a GitHub artifact attestation Tag releases now attest the raw binaries and ZIP archives in a signing job that runs no repository code, publish the bundle as plugin.sigstore.json, and verify every asset against it before publishing. The workflow_dispatch path is gone because its signature would carry refs/heads/main, and the tag must now equal manifest.json version. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 220 +++++++++++++++++++++++++++++----- README.md | 2 +- docs/DEVELOPMENT.md | 25 ++++ 3 files changed, 219 insertions(+), 28 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1d915cb..db9c5ce 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,88 +1,254 @@ +# Builds, signs, and publishes a release from a pushed tag vX.Y.Z that matches +# manifest.json "version". +# +# The signature is a GitHub artifact attestation (Sigstore keyless). Its +# certificate records this workflow at the tag, which is the identity Silo +# servers and the approved community catalog check, so releases run only from a +# tag push. +# +# Artifacts are not trusted between jobs: any job in the run can replace an +# artifact by name. The checksums and the Sigstore bundle travel as job +# outputs, the signing job attests those checksums without downloading or +# running anything from the repository, and the release job checks the +# downloaded files against the same checksums before publishing. name: Release on: push: tags: - 'v*' - workflow_dispatch: -permissions: - contents: write +permissions: {} jobs: - release: + build: + name: Build release assets runs-on: ubuntu-24.04 timeout-minutes: 45 + permissions: + contents: read + outputs: + tag: ${{ steps.version.outputs.tag }} + version: ${{ steps.version.outputs.version }} + checksums: ${{ steps.assets.outputs.checksums }} steps: - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 with: - fetch-depth: 0 + persist-credentials: false + # No module or build cache: a signed release must not consume cache + # entries that other workflow runs in the repository could have written. - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 with: go-version-file: go.mod + cache: false - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 with: python-version: '3.13' - - name: Determine version + - name: Check the tag against manifest.json id: version + env: + EVENT_NAME: ${{ github.event_name }} + REF: ${{ github.ref }} run: | - if [[ "$GITHUB_REF" == refs/tags/v* ]]; then - tag="${GITHUB_REF_NAME}" - else - latest=$(git tag -l 'v*' --sort=-v:refname | head -n1) - if [ -z "$latest" ]; then - version=$(jq -r '.version' manifest.json) - else - base="${latest#v}" - IFS='.' read -r major minor patch <<< "$base" - version="${major}.${minor}.$((patch + 1))" - fi - tag="v${version}" - git tag "$tag" - git push origin "refs/tags/${tag}" + set -euo pipefail + if [ "$EVENT_NAME" != "push" ] || [[ "$REF" != refs/tags/v* ]]; then + echo "::error::Releases run only from a pushed tag vX.Y.Z (got '${EVENT_NAME}' on '${REF}')." + exit 1 fi - echo "version=${tag#v}" >> "$GITHUB_OUTPUT" + tag="${REF#refs/tags/}" + version="${tag#v}" + manifest_version="$(jq -er '.version' manifest.json)" + if [ "$manifest_version" != "$version" ]; then + echo "::error file=manifest.json::manifest.json version is '${manifest_version}', but the tag is ${tag}." + exit 1 + fi + echo "version=${version}" >> "$GITHUB_OUTPUT" echo "tag=${tag}" >> "$GITHUB_OUTPUT" - name: Build release archives - run: make dist VERSION="${{ steps.version.outputs.version }}" + env: + VERSION: ${{ steps.version.outputs.version }} + run: make dist VERSION="$VERSION" - name: Prepare release assets + id: assets # The Silo plugin catalog and server install raw binaries named # plugin-- and verify them against checksums.txt. Publish # those alongside the reproducible ZIP archives from `make dist`. + env: + VERSION: ${{ steps.version.outputs.version }} run: | set -euo pipefail - version="${{ steps.version.outputs.version }}" mkdir -p release cp dist/*.zip release/ cp dist/checksums.txt release/checksums.txt for platform in linux-amd64 linux-arm64 darwin-arm64; do - archive="dist/silo-plugin-tailscale-${version}-${platform}.zip" + archive="dist/silo-plugin-tailscale-${VERSION}-${platform}.zip" unzip -p "$archive" plugin > "release/plugin-${platform}" chmod 0755 "release/plugin-${platform}" (cd release && sha256sum "plugin-${platform}" >> checksums.txt) done cat release/checksums.txt + # checksums.txt lists every published file except itself and the + # bundle, and is the attestation's subject list. base64 keeps the + # multi-line file a single-line job output. + echo "checksums=$(base64 -w0 release/checksums.txt)" >> "$GITHUB_OUTPUT" + rm release/checksums.txt + + - name: Upload release assets + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: release-assets + path: release/ + if-no-files-found: error + retention-days: 5 + + # Holds the signing permission. It checks nothing out, downloads nothing, + # and runs no repository code: its subjects are the checksums the build job + # returned as an output. + attest: + name: Sign release assets + needs: build + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + id-token: write + attestations: write + outputs: + bundle: ${{ steps.bundle.outputs.bundle }} + steps: + - name: Write and check the subject list + env: + CHECKSUMS: ${{ needs.build.outputs.checksums }} + VERSION: ${{ needs.build.outputs.version }} + run: | + set -euo pipefail + file="${RUNNER_TEMP}/subjects.txt" + printf '%s' "$CHECKSUMS" | base64 -d > "$file" + if grep -Evx '[0-9a-f]{64} [A-Za-z0-9._-]+' "$file"; then + echo "::error::The build job's checksums have an unexpected line (above)." + exit 1 + fi + expected="" + for platform in linux-amd64 linux-arm64 darwin-arm64; do + expected+="plugin-${platform}"$'\n'"silo-plugin-tailscale-${VERSION}-${platform}.zip"$'\n' + done + expected="$(printf '%s' "$expected" | sort)" + actual="$(awk '{print $2}' "$file" | sort)" + if [ "$expected" != "$actual" ]; then + echo "::error::The build job's checksums do not list exactly the release assets." + printf 'expected:\n%s\nactual:\n%s\n' "$expected" "$actual" + exit 1 + fi + cat "$file" + + - name: Attest build provenance + id: attest + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-checksums: ${{ runner.temp }}/subjects.txt + + - name: Return the bundle + id: bundle + env: + BUNDLE_PATH: ${{ steps.attest.outputs.bundle-path }} + run: | + set -euo pipefail + jq -e '.mediaType' "$BUNDLE_PATH" >/dev/null + encoded="$(base64 -w0 "$BUNDLE_PATH")" + # Job outputs are capped at 1 MB per job, counted as UTF-16. + if [ "${#encoded}" -gt 400000 ]; then + echo "::error::The Sigstore bundle is too large to return as a job output (${#encoded} base64 characters)." + exit 1 + fi + echo "bundle=${encoded}" >> "$GITHUB_OUTPUT" + + release: + name: Publish release + needs: [build, attest] + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + steps: + - name: Download release assets + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: release-assets + path: release + + - name: Check assets against the build job's checksums + env: + CHECKSUMS: ${{ needs.build.outputs.checksums }} + BUNDLE: ${{ needs.attest.outputs.bundle }} + run: | + set -euo pipefail + printf '%s' "$CHECKSUMS" | base64 -d > "${RUNNER_TEMP}/checksums.txt" + if grep -Evx '[0-9a-f]{64} [A-Za-z0-9._-]+' "${RUNNER_TEMP}/checksums.txt"; then + echo "::error::The build job's checksums have an unexpected line (above)." + exit 1 + fi + expected="$(awk '{print $2}' "${RUNNER_TEMP}/checksums.txt" | sort)" + actual="$(find release -mindepth 1 -maxdepth 1 -printf '%f\n' | sort)" + if [ "$expected" != "$actual" ]; then + echo "::error::The downloaded artifact does not hold exactly the expected files." + printf 'expected:\n%s\nactual:\n%s\n' "$expected" "$actual" + exit 1 + fi + cp "${RUNNER_TEMP}/checksums.txt" release/checksums.txt + (cd release && sha256sum --check --strict checksums.txt) + printf '%s' "$BUNDLE" | base64 -d > release/plugin.sigstore.json + jq -e '.mediaType' release/plugin.sigstore.json >/dev/null + + # Checks the bundle the way Silo servers and the approved community + # catalog do, pinned to this workflow at the tag, so a release they + # would refuse is never published. + - name: Verify the bundle against this workflow's identity + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ needs.build.outputs.tag }} + run: | + set -euo pipefail + signer="https://github.com/Silo-Community/silo-plugin-tailscale/.github/workflows/release.yml@refs/tags/${TAG}" + for asset in $(awk '{print $2}' release/checksums.txt); do + gh attestation verify "release/${asset}" \ + --bundle release/plugin.sigstore.json \ + --repo Silo-Community/silo-plugin-tailscale \ + --cert-identity "$signer" \ + --cert-oidc-issuer https://token.actions.githubusercontent.com \ + --source-ref "refs/tags/${TAG}" \ + --deny-self-hosted-runners + done - name: Create GitHub Release uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2 with: - tag_name: ${{ steps.version.outputs.tag }} + tag_name: ${{ needs.build.outputs.tag }} files: | release/plugin-linux-amd64 release/plugin-linux-arm64 release/plugin-darwin-arm64 release/*.zip release/checksums.txt + release/plugin.sigstore.json generate_release_notes: true - - name: Notify approved community catalog + # Separate from release so a failed dispatch can be re-run on its own. + dispatch: + name: Notify approved community catalog + needs: [build, release] + runs-on: ubuntu-24.04 + timeout-minutes: 5 + permissions: {} + steps: + - name: Send plugin_release_published env: DISPATCH_TOKEN: ${{ secrets.SILO_PLUGINS_DISPATCH_TOKEN }} + TAG: ${{ needs.build.outputs.tag }} run: | if [ -z "$DISPATCH_TOKEN" ]; then echo "::warning::SILO_PLUGINS_DISPATCH_TOKEN is not set; catalog was not notified." @@ -94,4 +260,4 @@ jobs: -H "Authorization: Bearer ${DISPATCH_TOKEN}" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/Silo-Community/silo-plugins/dispatches \ - -d "$(printf '{"event_type":"plugin_release_published","client_payload":{"repo":"Silo-Community/silo-plugin-tailscale","tag":"%s"}}' "${{ steps.version.outputs.tag }}")" + -d "$(printf '{"event_type":"plugin_release_published","client_payload":{"repo":"Silo-Community/silo-plugin-tailscale","tag":"%s"}}' "$TAG")" diff --git a/README.md b/README.md index 5bb6eff..34727ca 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Access Silo over HTTPS through your Tailscale network. No separate Tailscale dae Requires a Silo server with network-access plugin support, with MagicDNS and HTTPS certificates enabled in Tailscale. -1. Install **Tailscale** from the plugin catalog in Silo (enable **Include approved community plugins** in plugin settings). To install manually instead, [build the plugin](docs/DEVELOPMENT.md#build-and-verify), extract the ZIP, and upload its `plugin` executable. +1. Install **Tailscale** from the plugin catalog in Silo (enable **Include approved community plugins** in plugin settings). To install manually instead, download `plugin--` from a [release](https://github.com/Silo-Community/silo-plugin-tailscale/releases) and [verify its signature](docs/DEVELOPMENT.md#releases), or [build the plugin](docs/DEVELOPMENT.md#build-and-verify) and extract the ZIP, then upload the `plugin` executable. 2. Enable the plugin, choose a hostname, and optionally enter a Tailscale auth key. 3. Save, then select **Connect** in **Settings > Network Access**. Sign in if prompted. 4. Open the reported HTTPS URL from a device running Tailscale. Silo apps with server discovery find a server whose hostname is `silo` on their own; for another hostname, type just that name. Check the hostname in the reported URL: if an older `silo` machine is still in your tailnet (for example after a reinstall), the new node is named `silo-1`, and apps probing `silo` reach the old one. Remove the stale machine in the Tailscale admin console. Turn **Discovery** off to keep port 80 closed. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 3854c00..332827a 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -167,6 +167,31 @@ Real-tailnet/server playback QA has not been performed by the automated tests. No Apple or Android API changes are needed: clients install Tailscale separately and use the provider's reported server URL. +## Releases + +Releases run only from a pushed tag. Bump `version` in `manifest.json` and the +`VERSION` default in the Makefile, merge that to `main`, then tag the merged +commit `vX.Y.Z` with the same version and push the tag. The release workflow +refuses a tag that does not equal `manifest.json` `version`. + +The workflow builds with `make dist`, then signs the raw binaries +`plugin--` and the ZIP archives with a GitHub artifact attestation. +Signing runs in a separate job that holds the signing token and runs no +repository code. The release carries the Sigstore bundle as +`plugin.sigstore.json` beside the binaries, archives, and `checksums.txt`, and is +published only after every file verifies against that bundle. Silo servers check +the signature before installing when the approved community catalog lists the +bundle. + +To verify a download yourself: + +```sh +gh attestation verify plugin-linux-amd64 --repo Silo-Community/silo-plugin-tailscale --source-ref refs/tags/vX.Y.Z --deny-self-hosted-runners +``` + +Add `--bundle plugin.sigstore.json` to verify against the bundle from the release +instead of the copy GitHub stores. + ## HTTPS and tags The plugin automatically serves Silo over HTTPS using an embedded `tsnet` node. It does not require or configure a separate host `tailscaled` process or `tailscale serve` command. Enable MagicDNS and HTTPS certificates in the tailnet before connecting. A node can join the tailnet before its HTTPS certificate is ready. The plugin reports that distinction and retries certificate issuance with backoff from 15 seconds to five minutes, honoring a longer certificate-authority retry delay. It advertises a usable HTTPS origin only after certificate acquisition and listener setup succeed. From 30ca63c59b31319412f53bbc8cd6910300d24319 Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:11:16 -0500 Subject: [PATCH 2/3] ci(release): refuse a tag whose commit is not on main The approved community catalog lists a release signed by this workflow only when its commit is on the default branch. Checking that before the build stops a release the catalog would refuse from being published. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/release.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index db9c5ce..5e828c0 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -34,6 +34,7 @@ jobs: steps: - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 with: + fetch-depth: 0 persist-credentials: false # No module or build cache: a signed release must not consume cache @@ -65,6 +66,17 @@ jobs: echo "::error file=manifest.json::manifest.json version is '${manifest_version}', but the tag is ${tag}." exit 1 fi + # The approved community catalog lists a release signed by this + # workflow only when its commit is on the default branch, so a tag + # on an unmerged branch is refused here, before anything is built. + git rev-parse --verify --quiet refs/remotes/origin/main >/dev/null || { + echo "::error::origin/main was not fetched." + exit 1 + } + if ! git merge-base --is-ancestor "$GITHUB_SHA" refs/remotes/origin/main; then + echo "::error::Tag ${tag} (${GITHUB_SHA}) is not on main. Merge the release commit first, then tag it." + exit 1 + fi echo "version=${version}" >> "$GITHUB_OUTPUT" echo "tag=${tag}" >> "$GITHUB_OUTPUT" From d7c49b96b7027f5819596795f7d38a227e4c4043 Mon Sep 17 00:00:00 2001 From: Quick104 <31828688+Quick104@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:11:30 -0500 Subject: [PATCH 3/3] docs: say a release tag must be on main Co-Authored-By: Claude Fable 5.2 --- docs/DEVELOPMENT.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 484d679..c06ef49 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -172,7 +172,8 @@ and use the provider's reported server URL. Releases run only from a pushed tag. Bump `version` in `manifest.json` and the `VERSION` default in the Makefile, merge that to `main`, then tag the merged commit `vX.Y.Z` with the same version and push the tag. The release workflow -refuses a tag that does not equal `manifest.json` `version`. +refuses a tag that does not equal `manifest.json` `version`, or whose commit +is not on `main`. The workflow builds with `make dist`, then signs the raw binaries `plugin--` and the ZIP archives with a GitHub artifact attestation.