docs: document authenticated apt installs

README.md

@@ -13,13 +13,32 @@ A command-line interface for [Forgejo](https://forgejo.org/), built with [Comman
 
 ### With apt (Debian/Ubuntu — recommended)
 
-The package is published to the Debian registry of the forge itself. One-time setup:
+The package is published to the Debian registry of the forge itself. The
+`heavy-duty` organization is private, so installation requires a Forgejo user
+that belongs to the organization and a personal access token that can read its
+packages. One-time setup:
 
 ```bash
-curl -fsSL https://forgejo.heavyduty.builders/heavy-duty/stoke/raw/branch/main/scripts/install-apt.sh | bash
+export FORGE_USER=your-forgejo-login
+read -rsp 'Forgejo token: ' FORGE_TOKEN && echo && export FORGE_TOKEN
+curl -fsSLo /tmp/stoke-install-apt.sh \
+  https://forgejo.heavyduty.builders/heavy-duty/stoke/raw/branch/main/scripts/install-apt.sh
+sudo --preserve-env=FORGE_USER,FORGE_TOKEN bash /tmp/stoke-install-apt.sh
+unset FORGE_TOKEN
 ```
 
-or manually. First add the forge's registry as an apt source:
+The installer keeps the credentials out of the source URL in a root-readable
+apt auth file. To configure that file manually before adding the source:
+
+```bash
+sudo install -d -m 0755 /etc/apt/auth.conf.d
+printf 'machine forgejo.heavyduty.builders\nlogin %s\npassword %s\n' \
+  "$FORGE_USER" "$FORGE_TOKEN" \
+  | sudo tee /etc/apt/auth.conf.d/forgejo-heavy-duty.conf >/dev/null
+sudo chmod 0600 /etc/apt/auth.conf.d/forgejo-heavy-duty.conf
+```
+
+Then add the forge's registry as an apt source:
 
 ```bash
 sudo install -d /etc/apt/keyrings
@@ -46,7 +65,7 @@ sudo apt-get update && sudo apt-get install stoke
 
 Upgrades then arrive through regular `apt-get upgrade`. `install-apt.sh` performs all of the above, adding the NodeSource repository only when no already-configured apt source offers a new-enough nodejs.
 
-Note: apt releases that verify OpenPGP with `sqv` (Debian 13+, apt >= 2.9) currently reject the signature Forgejo generates for its Debian registry (an upstream signing bug). `install-apt.sh` detects this and falls back to a `[trusted=yes]` source — integrity then relies on HTTPS to the forge. The script prefers the signed source, so setups heal automatically once the forge is fixed.
+Note: apt releases that verify OpenPGP with `sqv` (Debian 13+, apt >= 2.9) may reject signatures produced by affected Forgejo versions. `install-apt.sh` permits its `[trusted=yes]` compatibility fallback only when apt reports an explicit signature failure. Authentication, network, and all other update failures are fatal and leave the `signed-by=` source unchanged, so a transient error cannot silently disable verification.
 
 As a fallback, each release also has the `.deb` attached for direct install: `sudo dpkg -i stoke_<version>_all.deb`.
 

changelog.d/1.md

@@ -0,0 +1 @@
+- Private apt installs now keep credentials out of source URLs and retain signature verification after non-signature update failures. (#1).