Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

docs: describe automatic updates and how they were validated

baiyuzeb42550314943
diff --git a/design/auto-update.md b/design/auto-update.md
new file mode 100644
index 0000000..8cd7384
--- /dev/null
+++ b/design/auto-update.md
@@ -0,0 +1,141 @@
+# Automatic updates
+
+Since 2.3.0 PasteFerry checks for new versions, shows the release notes in the
+interface language and, after the user confirms, downloads, verifies and
+installs the new version and reopens itself. Versions before 2.3.0 have no
+updater; their users install 2.3.0 once by hand.
+
+## Update list
+
+The source of truth is `updates/latest.json` in the GitHub repository. Gitee
+mirrors it (`scripts/gitee-mirror.sh`). The app reads both at the same time:
+
+- `https://raw.githubusercontent.com/baiyuze/pasteferry/main/updates/latest.json`
+- `https://gitee.com/baiyuze/pasteferry/raw/main/updates/latest.json`
+
+Each list has a detached signature next to it (`latest.json.sig`, base64
+Ed25519 over the exact bytes). The app keeps the first valid list, waits two
+more seconds for the other source, and uses the newer of the two. A list with
+a wrong signature is ignored.
+
+```json
+{
+ "schema": 1,
+ "latest": "2.3.0",
+ "date": "2026-10-20",
+ "mirrors": [
+ { "source": "gitee", "base": "https://gitee.com/baiyuze/pasteferry/releases/download/v2.3.0/" },
+ { "source": "github", "base": "https://github.com/baiyuze/pasteferry/releases/download/v2.3.0/" }
+ ],
+ "assets": {
+ "mac-arm64": { "name": "PasteFerry-mac-apple-silicon.dmg", "size": 24536429, "sha256": "…" }
+ },
+ "releases": [
+ { "version": "2.3.0", "date": "2026-10-20",
+ "notes": { "en": { "changes": ["…"], "fixes": ["…"] }, "zh-Hans": {}, "zh-Hant-TW": {}, "zh-Hant-HK": {}, "ja": {} } }
+ ]
+}
+```
+
+- Asset keys: `mac-arm64`, `mac-x64`, `mac-universal`, `windows-setup`,
+ `windows-portable`, `linux-{amd64,arm64}-{deb,tar}`.
+- `releases` keeps the newest 10 versions so a user several versions behind
+ sees every change since their version. Missing languages fall back
+ zh-Hant-HK → zh-Hant-TW → zh-Hans → en.
+- Release notes are written in `tools/release/notes.py`, five languages per
+ item. `tools/release/manifest.py X.Y.Z` checks that every language is present
+ and every file matches `release/SHA256SUMS`, writes the list and signs it.
+
+## Signing key
+
+`client-core/cmd/updatesign -genkey` created the key on 2026-10-19. The private
+key exists only in the login keychain of the release Mac (generic password,
+service `pasteferry-update-signing-key`); the public key is compiled into
+`client-core/internal/update/keys.go`. Without the private key no version can
+be shipped through the updater, so keep an offline backup: in Keychain Access,
+open the item, show the password and store it with the other recovery
+material. To rotate, add the new public key next to the old one, ship a
+release signed with the old key, and drop the old key later.
+
+## Check, download, install
+
+The background service does the network work, so a download continues if the
+window is closed, and Go's standard library provides HTTP, SHA-256 and
+Ed25519.
+
+1. Check one minute after start, then every 24 hours, unless "Check for
+ updates automatically" is off. The request carries no identifier
+ (`User-Agent: PasteFerry`). A found version that is not skipped is put in
+ `Status.update_available`; the sidebar shows a hint.
+2. Download the asset for this install into `<data>/updates/<version>/`,
+ first from the mirror that served the list, then from the other. The file is
+ kept only if its size and SHA-256 match the signed list.
+3. Prepare while the UI is still open, so errors can still be shown:
+ - macOS: mount the DMG, copy the app next to the installed one (same volume)
+ as `.PasteFerry-<version>.app`, check version, bundle ID and
+ `codesign --verify --deep --strict`.
+ - Windows portable / Linux tar.gz: extract next to the installed folder as
+ `.PasteFerry-update-<version>/PasteFerry`, check the main files exist.
+4. Start the updater: a copy of the daemon named `pasteferry-updater`, which
+ starts a second, detached copy of itself and exits. The Windows installer
+ stops `pasteferryd.exe` by name and by process tree; the renamed, detached
+ updater survives both.
+5. The UI quits. The updater waits for it, then:
+ - macOS: renames the old app aside and the new one into place, restarts the
+ LaunchAgent with `launchctl kickstart -k` if it points into this app, and
+ reopens the app with `open --env HOME=…`.
+ - Windows installer: runs `PasteFerry-Setup.exe /VERYSILENT /SUPPRESSMSGBOXES
+ /NORESTART /NOCANCEL /LOG=…`; the installer stops the old processes and
+ starts the background service. The updater reopens the UI.
+ - Windows portable / Linux tar.gz: stops the old background service and its
+ supervisor (only processes whose executable is in the app folder), swaps
+ the folders, starts `pasteferryd -supervise` and the UI.
+ - Linux .deb: `pkexec dpkg -i` (the system asks for the password because
+ `/opt` needs root), then restarts the background service and the UI.
+6. The result goes to `<data>/updates/result.json`; the new background service
+ reads it once and the UI says "Updated to X". On failure the old version
+ stays and is reopened.
+
+An install that cannot replace itself (development build, macOS app running
+from the DMG or a translocated path, unwritable folder, no package for this
+platform) still shows the release notes and offers the download page instead.
+
+## Testing
+
+A file `update-sources.json` in the data directory replaces the two list URLs
+(`[{"name": "test", "manifest": "http://…/latest.json"}]`). The list still has
+to carry a valid signature, so this cannot change what gets installed.
+
+Validation for 2.3.0 (2026-10-19): CI built a 2.3.0 base and a 2.3.1 test
+version from branches that differed only in the version number. The Mac served
+a list signed with the release key and the packages over the Parallels
+network. Each install started at 2.3.0 and was updated through the background
+service's API, the same calls the window makes.
+
+| Install | Machine | Result |
+| --- | --- | --- |
+| macOS app | Mac (Apple silicon), separate `HOME` | App swapped in 0.6 s, reopened, the 2.3.1 service reported "Updated to 2.3.1" |
+| Windows installer | Windows 11 VM | Silent install in 3.5 s, window reopened, pairings kept |
+| Windows portable | Windows 11 VM | Folder swapped 50 ms after the old service stopped; service and window reopened |
+| Linux .deb | Ubuntu 24.04 VM (x64), from the window | polkit asked for the password; window reopened with "Updated to 2.3.1" |
+| Linux tar.gz | Ubuntu 24.04 VM (x64), window open | Folder swapped 0.2 s after the window quit; service and window reopened |
+
+Problems found and fixed during the validation:
+
+- The supervisor restarted the old service while its folder was being
+ replaced. The updater now stops the supervisor first and retries the rename
+ for 15 seconds.
+- On Windows the updater's working directory was inside the folder it
+ replaced, which blocks the rename. It now runs in its own folder.
+- A failed install that did not restart the service (polkit denied) was never
+ shown. The service rereads `result.json` when it changes.
+- macOS `open` could activate another running copy with the same bundle ID
+ instead of the replaced app; it now uses `open -n`.
+- The service waited for the window's event stream before exiting, so
+ restarting it with the window open left the old process holding the
+ single-instance lock (seen on Linux). It now waits at most two seconds.
+
+Notes for repeating the test: `pkexec` only shows a password prompt for a
+process in the graphical session, so on Linux start the service with
+`systemd-run --user --scope`, not from an SSH shell. On Windows, start test
+processes with `Win32_Process.Create`; `prlctl exec` waits for every child.