Skip to content

Free fork of NotProton: Windows Steam games in Mac Steam, on CodeWeavers' Wine and Apple's Game Porting Toolkit

build(signing): sign releases with a stable self-signed identity

raymondchinsf8b85032d29a
diff --git a/Makefile b/Makefile
index 3047cfb..f42c3a9 100644
--- a/Makefile
+++ b/Makefile
@@ -722,7 +722,10 @@ APP_VERSION := $(shell sed -n 's/^\#define BRIDGEPLAY_VERSION "\(.*\)"/\1/p' dy
APP_BUILD := $(shell sed -n 's/^\#define BRIDGEPLAY_BUILD \([0-9][0-9]*\)$$/\1/p' dylib/version.h)
APP_UPSTREAM := $(shell sed -n 's/^\#define NOTPROTON_VERSION "\(.*\)"/\1/p' dylib/version.h)
-APP_SIGN_ID ?= -
+# The app's code signing identity. Ad hoc (-) by default, so any checkout builds; a release
+# uses a stable self-signed identity (BRIDGEPLAY_SIGN_IDENTITY, see docs/RELEASING.md) so the
+# designated requirement, and the macOS permissions keyed to it, survive updates.
+APP_SIGN_ID ?= $(or $(BRIDGEPLAY_SIGN_IDENTITY),-)
# The icon name must match CFBundleIconFile/CFBundleIconName in app/Info.plist.
ICON_NAME := Bridgeplay
@@ -793,8 +796,17 @@ app: app-payload $(ICON_CAR)
exit 1; \
fi
@echo "==> Payload complete in the bundle"
+ @# Inside out, so Sparkle's helpers carry the same identity as the app. No hardened
+ @# runtime: library validation needs a Team ID, which a self-signed identity has none of.
+ @sparkle="$(APP_BUNDLE)/Contents/Frameworks/Sparkle.framework/Versions/B"; \
+ codesign -f -s "$(APP_SIGN_ID)" -i org.sparkle-project.Sparkle.Autoupdate "$$sparkle/Autoupdate" || exit 1; \
+ for code in "$$sparkle"/XPCServices/*.xpc "$$sparkle/Updater.app" \
+ "$(APP_BUNDLE)/Contents/Frameworks/Sparkle.framework"; do \
+ codesign -f -s "$(APP_SIGN_ID)" --preserve-metadata=entitlements "$$code" || exit 1; \
+ done
codesign -f -s "$(APP_SIGN_ID)" "$(APP_BUNDLE)"
- codesign --verify --strict "$(APP_BUNDLE)"
+ codesign --verify --strict --deep "$(APP_BUNDLE)"
+ @codesign -d -r- "$(APP_BUNDLE)" 2>&1 | sed -n 's/^#* *designated => /==> Designated requirement: /p'
@echo "==> Built $(APP_BUNDLE) ($(APP_VERSION) build $(APP_BUILD), based on NotProton $(APP_UPSTREAM))"
app-zip: app
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index f9d52eb..8ac5053 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -51,8 +51,8 @@ installation. `VersioningTests` guards both.
the keychain.
4. Release: `scripts/release-local.sh` (notes default to the commit subjects since the
previous `vX.Y.Z` release; pass a string to override). It builds with
- `scripts/build-local.sh --checks`, signs the zip with the EdDSA key in the login
- keychain, writes an appcast with `minimumSystemVersion` 26.0, packages the installer from the
+ `scripts/build-local.sh --checks`, signs the app with the `Bridgeplay Release` identity
+ (see Signing), signs the zip with the EdDSA key in the login keychain, writes an appcast with `minimumSystemVersion` 26.0, packages the installer from the
same app (`scripts/package-installer.sh`) and publishes `vX.Y.Z` as Latest with all three.
Any other release in the repository (a DXMT build, say) must be created with
@@ -70,11 +70,68 @@ Any other release in the repository (a DXMT build, say) must be created with
## Signing
-Sparkle trusts an update when its EdDSA signature matches `SUPublicEDKey`; the archive is
-checked before extraction (`SUVerifyUpdateBeforeExtraction`). Apple code signing only has
-to be valid, not the same identity: an ad hoc build updates an ad hoc build, and a later
-build signed with "NotProton Local Signing" is accepted as well. Losing the keychain key
-means no installed copy can update again, so keep a backup (`generate_keys -x`).
+Two signatures, for different things:
+
+- **Sparkle (EdDSA)** decides whether an update is trusted: its signature must match
+ `SUPublicEDKey`, and the archive is checked before extraction
+ (`SUVerifyUpdateBeforeExtraction`). Losing that keychain key means no installed copy can
+ update again, so keep a backup (`generate_keys -x`).
+- **Apple code signing** has to be valid (`codesign --verify --strict --deep`), and its
+ designated requirement is what macOS keys permissions to (App Management, which lets
+ Bridgeplay patch Steam.app). An ad hoc signature's requirement is the cdhash, which is new
+ with every build, so macOS treats each update as a different app: the toggle in System
+ Settings still looks on, but no longer applies. Releases are therefore signed with a
+ stable self-signed identity, and the requirement becomes
+ `identifier "com.bridgeplay.Bridgeplay" and certificate leaf = H"<sha1>"`, the same for
+ every build signed with that certificate.
+
+`make app` signs with `APP_SIGN_ID`, which defaults to `$BRIDGEPLAY_SIGN_IDENTITY` and
+then to ad hoc (`-`), so any checkout still builds. Sparkle's helpers (`Autoupdate`,
+`Updater.app`, its XPC services) are signed with the same identity, inside out. There is no
+hardened runtime: library validation needs a Team ID, which a self-signed certificate does
+not have. `scripts/release-local.sh` uses `BRIDGEPLAY_SIGN_IDENTITY` (default
+`Bridgeplay Release`), refuses ad hoc, stops if the identity is not in the keychain, prints
+the designated requirement and stops unless it is the certificate form signed by that
+identity. Changing the identity or its certificate, or marking it trusted (which can turn
+`certificate leaf` into `certificate root`), changes the requirement, and every user has to
+grant App Management once more. The first release signed this way does that once as well,
+coming from ad hoc.
+
+### Creating the release identity (once)
+
+```sh
+scripts/make-release-cert.sh
+```
+
+It creates the self-signed `Bridgeplay Release` code signing identity (RSA 3072, 20 years)
+in the login keychain, asks for a backup password (12 characters or more) and writes
+`~/Desktop/Bridgeplay-Release.p12`. Move the `.p12` and its password into a password
+manager and delete the file from the Desktop; on a new Mac, double-click the `.p12` to
+import it. Without the backup, a new certificate means one more App Management grant for
+every user. Do not change the certificate's Trust settings. The first `make app` with the
+identity asks for access to its key; choose Always Allow.
+
+## Compatibility reports
+
+The app's one-tap reports go to `https://bridgeplay.dev/api/report` (bridgeplay-web,
+`api/report.mjs`), which posts each one as a Discussion in the `compatibility-reports`
+category of this repository. `api/compat.mjs` counts them (only posts by the report bot)
+for the compatibility page, cached for an hour; `compat/games.json` holds the results a
+maintainer checked and wins over them. Both functions use the `BRIDGEPLAY_BOT_TOKEN`
+Vercel env var: a fine-grained token on this repository with Discussions read and write and
+nothing else.
+
+The app asks about a game at most once per Bridgeplay version (an answer, Not Now or an
+automatic report all count), so a release is when players get asked again about the games
+they play. In between, it asks again only if a game crashes after the player answered
+Smooth. Don't Ask About This Game in the card's menu stops the question for that game for
+good; Report This Game… on the Prefixes page always asks. It never asks about (or
+auto-shares) a game that `compat/games.json` already lists as tested on a Mac with the same
+chip (`tested_on`, `reports[].chip` or `reports[].device`, e.g. "M5 Max"); the app reads that
+file from `main` at most once a day and caches it, and asks as usual when it can't. Prefix ›
+Report Your Games… lists every game with a session in its log, minus those, for answering
+in one go; the reports go out one by one, within the endpoint's per-install limit of 50 an
+hour.
## Moving NotProton users over
diff --git a/scripts/build-local.sh b/scripts/build-local.sh
index cbaca44..3f0da46 100755
--- a/scripts/build-local.sh
+++ b/scripts/build-local.sh
@@ -200,7 +200,7 @@ zip_out=build/Bridgeplay.zip
rm -rf "$app_out" "$zip_out"
ditto out/Bridgeplay.app "$app_out"
ditto -c -k --keepParent "$app_out" "$zip_out"
-codesign --verify --strict "$app_out"
+codesign --verify --strict --deep "$app_out"
version=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$app_out/Contents/Info.plist")
sha=$(shasum -a 256 "$zip_out" | cut -d' ' -f1)
@@ -258,7 +258,8 @@ fi
print_timings
echo "==> Bridgeplay $version"
-echo " app $repo/$app_out (ad-hoc signed, codesign --verify --strict ok)"
+echo " app $repo/$app_out (codesign --verify --strict ok)"
+echo " signed $(codesign -d -r- "$app_out" 2>&1 | sed -n 's/^#* *designated => //p')"
echo " zip $repo/$zip_out"
echo " sha256 $sha"
if [ -n "$check_failures" ]; then
diff --git a/scripts/make-release-cert.sh b/scripts/make-release-cert.sh
new file mode 100755
index 0000000..6c7f47c
--- /dev/null
+++ b/scripts/make-release-cert.sh
@@ -0,0 +1,68 @@
+#!/bin/sh
+# One-time setup for whoever publishes Bridgeplay releases: create the self-signed
+# "Bridgeplay Release" code-signing identity in the login keychain and write a .p12
+# backup of it. Releases signed with the same identity keep the same designated
+# requirement, so macOS permissions such as App Management survive updates.
+# Losing the identity means every user grants those permissions once more.
+#
+# Usage: scripts/make-release-cert.sh [backup.p12]
+# Env: BRIDGEPLAY_SIGN_IDENTITY identity name (default "Bridgeplay Release")
+# KEYCHAIN keychain to import into (default: login keychain)
+# BP_P12_PASS backup password; asked for when unset
+set -eu
+
+name=${BRIDGEPLAY_SIGN_IDENTITY:-Bridgeplay Release}
+out=${1:-"$HOME/Desktop/$(printf '%s' "$name" | tr ' ' '-').p12"}
+keychain=${KEYCHAIN:-"$HOME/Library/Keychains/login.keychain-db"}
+
+die() { printf 'make-release-cert: %s\n' "$*" >&2; exit 1; }
+
+if security find-identity -p codesigning "$keychain" | grep -q "\"$name\""; then
+ printf '"%s" is already in %s; nothing to do.\n' "$name" "$keychain"
+ exit 0
+fi
+[ -e "$out" ] && die "$out already exists; move it or pass another path"
+
+if [ -z "${BP_P12_PASS:-}" ]; then
+ [ -t 0 ] || die "set BP_P12_PASS or run this in a terminal"
+ printf 'Password for the backup (keep it in your password manager): '
+ stty -echo; read -r BP_P12_PASS; stty echo; printf '\n'
+ printf 'Again: '
+ stty -echo; read -r again; stty echo; printf '\n'
+ [ "$BP_P12_PASS" = "$again" ] || die "the passwords do not match"
+fi
+[ ${#BP_P12_PASS} -ge 12 ] || die "use a password of at least 12 characters"
+export BP_P12_PASS
+
+# The private key exists in plain text only inside this folder, removed on exit.
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+umask 077
+
+openssl req -x509 -newkey rsa:3072 -nodes -days 7300 -subj "/CN=$name" \
+ -addext "keyUsage=critical,digitalSignature" \
+ -addext "extendedKeyUsage=critical,codeSigning" \
+ -addext "basicConstraints=critical,CA:false" \
+ -keyout "$work/key.pem" -out "$work/cert.pem" 2>/dev/null || die "openssl could not create the certificate"
+
+# OpenSSL 3 and later write a .p12 the keychain cannot read unless -legacy is given;
+# LibreSSL has no -legacy and already writes the old format.
+openssl pkcs12 -export -legacy -name "$name" -inkey "$work/key.pem" -in "$work/cert.pem" \
+ -passout env:BP_P12_PASS -out "$out" 2>/dev/null \
+ || openssl pkcs12 -export -name "$name" -inkey "$work/key.pem" -in "$work/cert.pem" \
+ -passout env:BP_P12_PASS -out "$out" \
+ || die "openssl could not write $out"
+
+security import "$out" -k "$keychain" -P "$BP_P12_PASS" -T /usr/bin/codesign >/dev/null \
+ || die "could not import the identity into $keychain"
+
+security find-identity -p codesigning "$keychain" | grep "\"$name\"" \
+ || die "the identity was imported but codesign cannot see it"
+
+cat <<EOF
+
+Done. "$name" is in your keychain and backed up to:
+ $out
+Move that file and its password into your password manager, then delete it here.
+The first build signed with it asks for access to the key: choose Always Allow.
+EOF
diff --git a/scripts/release-local.sh b/scripts/release-local.sh
index 46d5a70..13d9245 100755
--- a/scripts/release-local.sh
+++ b/scripts/release-local.sh
@@ -14,9 +14,10 @@
#
# The update is signed with the EdDSA key in this Mac's login keychain, created once with
# app/.build/artifacts/sparkle/Sparkle/bin/generate_keys; app/Info.plist's SUPublicEDKey
-# must be its public half. The version comes from dylib/version.h (scripts/bump-version.sh)
-# and must not have been released yet. HEAD must already be pushed to the Bridgeplay
-# repository's main.
+# must be its public half. The app is code signed with BRIDGEPLAY_SIGN_IDENTITY (default
+# "Bridgeplay Release", a self-signed identity in the login keychain). The version comes
+# from dylib/version.h (scripts/bump-version.sh) and must not have been released yet.
+# HEAD must already be pushed to the Bridgeplay repository's main.
set -eu
@@ -118,6 +119,17 @@ sparkle=app/.build/artifacts/sparkle/Sparkle/bin
[ -x "$sparkle/generate_appcast" ] || swift build --package-path app >/dev/null
[ -x "$sparkle/generate_appcast" ] || die "no Sparkle tools at $sparkle"
+# The app is signed with a stable self-signed identity, so its designated requirement (and
+# the macOS permissions keyed to it, such as App Management) stays the same across updates.
+# An ad hoc signature is the cdhash, new with every build. See docs/RELEASING.md (Signing).
+sign_identity=${BRIDGEPLAY_SIGN_IDENTITY:-Bridgeplay Release}
+[ "$sign_identity" != "-" ] || check "BRIDGEPLAY_SIGN_IDENTITY is ad hoc (-); a release needs the stable identity"
+if [ "$dry_run" -eq 0 ] && ! security find-identity -p codesigning | grep -Fq "\"$sign_identity\""; then
+ die "no code signing identity \"$sign_identity\" in the keychain; create it once (docs/RELEASING.md, Signing)"
+fi
+BRIDGEPLAY_SIGN_IDENTITY=$sign_identity
+export BRIDGEPLAY_SIGN_IDENTITY
+
if [ "$dry_run" -eq 1 ]; then
out=out/release
rm -rf "$out"
@@ -166,7 +178,15 @@ built=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$plist")
built_build=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' "$plist")
[ "$built" = "$version" ] && [ "$built_build" = "$build" ] \
|| check "built $built ($built_build), expected $version ($build) from dylib/version.h"
-codesign --verify --strict "$app" || die "$app is not validly signed; Sparkle rejects that"
+codesign --verify --strict --deep "$app" || die "$app is not validly signed; Sparkle rejects that"
+requirement=$(codesign -d -r- "$app" 2>&1 | sed -n 's/^#* *designated => //p')
+echo "==> designated requirement: $requirement"
+case "$requirement" in
+ 'identifier "com.bridgeplay.Bridgeplay" and certificate '*' = H"'*'"') ;;
+ *) check "$app is not signed with a certificate (ad hoc?), so macOS would forget its permissions on update" ;;
+esac
+codesign -dvv "$app" 2>&1 | grep -Fqx "Authority=$sign_identity" \
+ || check "$app is not signed by \"$sign_identity\""
# One archive and one appcast per feed. The appcast attached to the latest release is the
# feed, so each only needs the newest item; its enclosure points at this tag's zip.