security(apt): sign the published repository

The APT repo shipped no InRelease and no Release.gpg, so the install
instructions needed [trusted=yes] -- which tells apt to skip signature
verification entirely. That is worse than average here: the package
installs a root-invoked fan helper plus a polkit rule, and dpkg
maintainer scripts run as root. HTTPS authenticates the host during the
transfer; it says nothing about whether the bytes on gh-pages, or in any
cache in front of it, are the ones CI built.

Signs Release into InRelease and Release.gpg when APT_GPG_PRIVATE_KEY is
configured, publishes the public half, and switches the generated
index.html to signed-by= instructions. With no key set it publishes
unsigned as before but warns -- and deletes any previously published
signature, because a stale InRelease beside a regenerated Release breaks
apt update outright, which is worse for users than unsigned.

Also declares apt-utils: the step calls apt-ftparchive but installed only
dpkg-dev, working by luck of the runner image preinstalling it.

Verified by extracting the step from the YAML and running it against a
throwaway key: signatures verify against the published public key alone,
a tampered Release is rejected, and removing the key deletes the stale
signature files and reverts the index.

docs/development/apt-signing.md covers key generation and the two secrets.

Author: vietanhdev

.github/workflows/release.yml

@@ -135,14 +135,21 @@ jobs:
 
       - name: Update APT repository
         if: startsWith(github.ref, 'refs/tags/')
+        env:
+          # Unset until a signing key exists, in which case the step publishes
+          # unsigned and says so loudly rather than failing the release.
+          APT_GPG_PRIVATE_KEY: ${{ secrets.APT_GPG_PRIVATE_KEY }}
+          APT_GPG_PASSPHRASE: ${{ secrets.APT_GPG_PASSPHRASE }}
         run: |
           # This step publishes to a live APT repo that users have in their
           # sources.list. A half-finished run takes that repo down, so it fails
           # fast rather than pressing on.
           set -euo pipefail
 
-          # Install dpkg-scanpackages
-          sudo apt-get install -y dpkg-dev
+          # dpkg-dev provides dpkg-scanpackages; apt-utils provides
+          # apt-ftparchive. The runner image happens to preinstall apt-utils, so
+          # omitting it worked by luck rather than by declaration.
+          sudo apt-get install -y dpkg-dev apt-utils
 
           # Verify the .deb exists BEFORE touching the published repo. The old
           # order deleted the existing package first and copied second, so a glob
@@ -193,22 +200,97 @@ jobs:
           # Generate Release file
           apt-ftparchive release . > Release
 
-          # Create index page
-          cat > ../index.html << 'HTMLEOF'
+          # Sign it.
+          #
+          # An unsigned repository is why the install instructions needed
+          # [trusted=yes], a flag that tells apt to skip verification entirely.
+          # That matters more here than for most repos: this package ships a
+          # root-invoked fan helper and a polkit rule, and dpkg maintainer
+          # scripts run as root. HTTPS authenticates the host for the duration
+          # of the transfer; it says nothing about whether the bytes sitting on
+          # the branch, or in any cache in front of it, are the ones we built.
+          if [ -n "${APT_GPG_PRIVATE_KEY:-}" ]; then
+            GNUPGHOME="$(mktemp -d)"
+            export GNUPGHOME
+            chmod 700 "$GNUPGHOME"
+
+            printf '%s' "$APT_GPG_PRIVATE_KEY" | gpg --batch --quiet --import
+            key_id=$(gpg --batch --list-secret-keys --with-colons \
+                     | awk -F: '/^sec:/ {print $5; exit}')
+            if [ -z "$key_id" ]; then
+              echo "::error::APT_GPG_PRIVATE_KEY is set but contains no secret key"
+              exit 1
+            fi
+
+            # InRelease (inline signature) is what modern apt prefers;
+            # Release.gpg is the detached form older clients still look for.
+            gpg --batch --yes --pinentry-mode loopback \
+                --passphrase "${APT_GPG_PASSPHRASE:-}" --local-user "$key_id" \
+                --clearsign -o InRelease Release
+            gpg --batch --yes --pinentry-mode loopback \
+                --passphrase "${APT_GPG_PASSPHRASE:-}" --local-user "$key_id" \
+                -abs -o Release.gpg Release
+
+            # Publish the public half so users can pin it with signed-by=.
+            gpg --batch --armor --export "$key_id" > thinkutils-archive-keyring.asc
+
+            # Fail loudly rather than publishing a signature that does not
+            # verify -- apt treats a bad signature as harder breakage than none.
+            gpg --batch --verify Release.gpg Release
+            echo "signed the Release file with ${key_id}"
+
+            rm -rf "$GNUPGHOME"
+            unset GNUPGHOME
+            SIGNED=1
+          else
+            # Critical: a previous run may have published a signature. Leaving a
+            # stale InRelease next to a regenerated Release breaks apt outright
+            # for everyone, which is strictly worse than being unsigned.
+            rm -f InRelease Release.gpg thinkutils-archive-keyring.asc
+            SIGNED=0
+            echo "::warning::APT_GPG_PRIVATE_KEY is not configured. Publishing an \
+          UNSIGNED repository; users must keep [trusted=yes], which disables \
+          verification. See docs/development/apt-signing.md to set this up."
+          fi
+
+          # Create index page, matching whichever form was actually published.
+          if [ "$SIGNED" = "1" ]; then
+            sources_line='deb [signed-by=/usr/share/keyrings/thinkutils-archive-keyring.gpg] https://gh.vietanh.dev/ThinkUtils/apt ./'
+            cat > ../index.html << HTMLEOF
           <!DOCTYPE html>
           <html>
           <head><title>ThinkUtils APT Repository</title></head>
           <body>
           <h1>ThinkUtils APT Repository</h1>
           <p>Add this repository to install ThinkUtils via apt:</p>
           <pre>
+          curl -fsSL https://gh.vietanh.dev/ThinkUtils/apt/thinkutils-archive-keyring.asc \\
+            | sudo gpg --dearmor -o /usr/share/keyrings/thinkutils-archive-keyring.gpg
+          echo "${sources_line}" | sudo tee /etc/apt/sources.list.d/thinkutils.list
+          sudo apt update
+          sudo apt install thinkutils
+          </pre>
+          </body>
+          </html>
+          HTMLEOF
+          else
+            cat > ../index.html << 'HTMLEOF'
+          <!DOCTYPE html>
+          <html>
+          <head><title>ThinkUtils APT Repository</title></head>
+          <body>
+          <h1>ThinkUtils APT Repository</h1>
+          <p><strong>This repository is not signed.</strong> The command below uses
+          <code>[trusted=yes]</code>, which disables apt's signature checking.</p>
+          <pre>
           echo "deb [trusted=yes] https://gh.vietanh.dev/ThinkUtils/apt ./" | sudo tee /etc/apt/sources.list.d/thinkutils.list
           sudo apt update
           sudo apt install thinkutils
           </pre>
           </body>
           </html>
           HTMLEOF
+          fi
 
           # Commit and push
           cd ..

docs/development/apt-signing.md

@@ -0,0 +1,91 @@
+# Signing the APT repository
+
+The APT repository at `https://gh.vietanh.dev/ThinkUtils/apt` is published by the
+`Update APT repository` step in `.github/workflows/release.yml`. That step signs
+the `Release` file **if** a signing key is configured, and publishes unsigned
+with a loud warning if one is not.
+
+Until the key below exists, the repository is unsigned and users have to install
+with `[trusted=yes]`.
+
+## Why this matters here
+
+`[trusted=yes]` tells apt to skip signature verification entirely. For most
+repositories that is merely bad practice. For this one it is worse than average:
+
+- the package installs a fan-control helper that runs as root, plus a polkit
+  rule that grants access to it
+- dpkg maintainer scripts run as root at install time
+
+HTTPS authenticates the *host* for the duration of the transfer. It says nothing
+about whether the bytes sitting on the `gh-pages` branch, or in any cache in
+front of it, are the ones CI built. A signature is what carries that guarantee
+from the builder to the user's machine.
+
+## Generating the key
+
+Do this once, on a trusted machine — not in CI.
+
+```bash
+# A dedicated key, used for nothing else.
+gpg --quick-gen-key "ThinkUtils Archive Signing Key <you@example.com>" \
+    default default never
+
+# Note the key ID from the output, then export both halves.
+KEYID=<key-id-from-above>
+gpg --armor --export-secret-keys "$KEYID" > thinkutils-apt-private.asc
+gpg --armor --export "$KEYID"             > thinkutils-apt-public.asc
+```
+
+Keep `thinkutils-apt-private.asc` offline. It is the credential that lets anyone
+publish a package your users' machines will install as root.
+
+## Configuring CI
+
+Add two repository secrets (Settings → Secrets and variables → Actions):
+
+| Secret                 | Value                                             |
+| ---------------------- | ------------------------------------------------- |
+| `APT_GPG_PRIVATE_KEY`  | full contents of `thinkutils-apt-private.asc`     |
+| `APT_GPG_PASSPHRASE`   | the key's passphrase (omit if the key has none)   |
+
+The next tagged release will then publish `InRelease`, `Release.gpg`, and
+`thinkutils-archive-keyring.asc` alongside the packages, and the generated
+`index.html` will switch to `signed-by=` instructions automatically.
+
+## What users run once it is signed
+
+```bash
+curl -fsSL https://gh.vietanh.dev/ThinkUtils/apt/thinkutils-archive-keyring.asc \
+  | sudo gpg --dearmor -o /usr/share/keyrings/thinkutils-archive-keyring.gpg
+
+echo "deb [signed-by=/usr/share/keyrings/thinkutils-archive-keyring.gpg] https://gh.vietanh.dev/ThinkUtils/apt ./" \
+  | sudo tee /etc/apt/sources.list.d/thinkutils.list
+
+sudo apt update
+sudo apt install thinkutils
+```
+
+`signed-by=` scopes the key to this one repository, so it cannot be used to
+vouch for packages from anywhere else in the user's sources.
+
+## Rotating or removing the key
+
+Changing the key changes what users must trust, so treat it as a release event:
+publish the new public key, and expect `apt update` to fail for anyone still
+pinning the old one until they re-import.
+
+Removing the secrets makes the next release publish unsigned again. The workflow
+deletes any previously published `InRelease`, `Release.gpg`, and keyring file
+when it does — a stale signature next to a regenerated `Release` breaks `apt
+update` outright, which is worse for users than being unsigned.
+
+## Verifying by hand
+
+```bash
+curl -fsSL https://gh.vietanh.dev/ThinkUtils/apt/thinkutils-archive-keyring.asc \
+  | gpg --import
+curl -fsSLO https://gh.vietanh.dev/ThinkUtils/apt/Release
+curl -fsSLO https://gh.vietanh.dev/ThinkUtils/apt/Release.gpg
+gpg --verify Release.gpg Release
+```