Sign and notarize releases

Releases were ad-hoc signed, so every download had to be walked past Gatekeeper
by hand. Now that a Developer ID certificate is available, build-release.sh signs
with it, submits to Apple, staples the ticket and re-zips, then checks the result
with stapler and spctl. The release workflow runs that same script rather than a
CI-only copy, and refuses to publish at all if the signing secrets are missing,
so a misconfigured job fails loudly instead of quietly shipping an ad-hoc build.

A signed build no longer needs to disable library validation. Xcode re-signs the
embedded Sparkle framework with the app's own identity, so under a Developer ID
the two share a team and the check passes; only ad-hoc builds, whose signature
has no team for anything to match, still need the exemption. That is why there
are now two entitlement files, picked by PQA_ENTITLEMENTS_SUFFIX. The suffix is a
variable interpolated on the app target because overriding CODE_SIGN_ENTITLEMENTS
on the xcodebuild command line reaches every target, and the SPM packages then
fail looking for the file inside their own checkout.

The workflow also gained a manual trigger that builds, signs and notarizes but
publishes nothing, since otherwise the only way to find out whether the
credentials work is to cut a release and watch it fail.

Author: bsramin

.github/workflows/release.yml

@@ -3,6 +3,20 @@ name: Release
 on:
   release:
     types: [published]
+  # A dry run: builds, signs and notarizes exactly as a real release does, but
+  # publishes nothing. It is the only way to find out whether the signing and
+  # notarization secrets actually work, short of cutting a release and watching
+  # it fail. Worth running after any change to the credentials or this file.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to stand in for, only used to derive a version number"
+        required: false
+        # Well-formed but obviously not a real release, so a dry-run build is
+        # never mistaken for one. An all-zero date would derive a CFBundleVersion
+        # of 00000000.0, and this test exists precisely to avoid finding out the
+        # hard way whether something down the line objects to that.
+        default: "v1970-01-01.1"
 
 permissions:
   contents: write
@@ -27,25 +41,73 @@ jobs:
       - name: Derive versions from the tag
         id: version
         env:
-          TAG: ${{ github.event.release.tag_name }}
+          TAG: ${{ github.event.release.tag_name || inputs.tag }}
         run: |
           # Tag v2026-06-19.1 -> build number 20260619.1, which climbs with the
           # date so Sparkle always treats a newer release as an upgrade.
           stripped="${TAG#v}"
           build="${stripped//-/}"
           echo "build=$build" >> "$GITHUB_OUTPUT"
 
-      - name: Build release artifact
+      # The certificate goes into a throwaway keychain rather than the login one,
+      # so it exists only for this job and is deleted below whatever happens.
+      - name: Import the Developer ID certificate
+        env:
+          CERTIFICATE_P12: ${{ secrets.MACOS_CERTIFICATE_P12 }}
+          CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        run: |
+          if [[ -z "$CERTIFICATE_P12" ]]; then
+            echo "MACOS_CERTIFICATE_P12 is not set; a published release must be signed." >&2
+            exit 1
+          fi
+          keychain="$RUNNER_TEMP/signing.keychain-db"
+          password="$(uuidgen)"
+          echo "SIGNING_KEYCHAIN=$keychain" >> "$GITHUB_ENV"
+
+          printf '%s' "$CERTIFICATE_P12" | base64 --decode > "$RUNNER_TEMP/certificate.p12"
+          security create-keychain -p "$password" "$keychain"
+          # Without this the keychain relocks on a timer mid-build and signing
+          # fails partway through with a generic error.
+          security set-keychain-settings -lut 21600 "$keychain"
+          security unlock-keychain -p "$password" "$keychain"
+          security import "$RUNNER_TEMP/certificate.p12" -k "$keychain" \
+            -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
+          # Lets codesign use the key without the interactive "allow access"
+          # prompt, which nothing can answer on a runner.
+          security set-key-partition-list -S apple-tool:,apple:,codesign: \
+            -s -k "$password" "$keychain" > /dev/null
+          security list-keychain -d user -s "$keychain" login.keychain-db
+          rm -f "$RUNNER_TEMP/certificate.p12"
+
+      - name: Build, sign and notarize
         env:
           PQA_BUILD_VERSION: ${{ steps.version.outputs.build }}
-        run: ./scripts/build-release.sh
+          PQA_SIGN_IDENTITY: ${{ secrets.MACOS_SIGN_IDENTITY }}
+          PQA_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          NOTARY_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          NOTARY_ISSUER_ID: ${{ secrets.APPLE_API_ISSUER_ID }}
+          APPLE_API_KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }}
+        run: |
+          if [[ -z "$PQA_SIGN_IDENTITY" || -z "$NOTARY_KEY_ID" || -z "$APPLE_API_KEY_P8" ]]; then
+            echo "Signing or notarization secrets are missing; refusing to publish an unsigned build." >&2
+            exit 1
+          fi
+          # notarytool wants the key as a file. Write it outside the workspace and
+          # remove it on the way out, including when the build fails.
+          export NOTARY_KEY_PATH="$RUNNER_TEMP/notary-key.p8"
+          trap 'rm -f "$NOTARY_KEY_PATH"' EXIT
+          install -m 600 /dev/null "$NOTARY_KEY_PATH"
+          printf '%s' "$APPLE_API_KEY_P8" > "$NOTARY_KEY_PATH"
+          ./scripts/build-release.sh
 
       - name: Attach artifact to the release
+        if: github.event_name == 'release'
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.event.release.tag_name }}
         run: gh release upload "$TAG" dist/PassQuickAccess.zip --clobber
 
+      # Runs on a dry run too, so the Sparkle key is exercised along with the rest.
       - name: Sign the update
         id: sign
         env:
@@ -60,7 +122,9 @@ jobs:
           echo "signature=$(echo "$out" | sed -E 's/.*sparkle:edSignature="([^"]+)".*/\1/')" >> "$GITHUB_OUTPUT"
           echo "length=$(echo "$out" | sed -E 's/.*length="([0-9]+)".*/\1/')" >> "$GITHUB_OUTPUT"
 
+      # Skipped on a dry run: this one pushes to main.
       - name: Update the appcast on the default branch
+        if: github.event_name == 'release'
         env:
           TAG: ${{ github.event.release.tag_name }}
           BUILD: ${{ steps.version.outputs.build }}
@@ -92,3 +156,12 @@ jobs:
           git add docs/appcast.xml
           git commit -m "Publish $TAG to the appcast"
           git push origin main
+
+      # The runner is thrown away regardless, but the signing key should not
+      # outlive the step that needed it, including when the build failed.
+      - name: Remove the signing keychain
+        if: always()
+        run: |
+          if [[ -n "${SIGNING_KEYCHAIN:-}" && -f "$SIGNING_KEYCHAIN" ]]; then
+            security delete-keychain "$SIGNING_KEYCHAIN"
+          fi

CHANGELOG.md

@@ -8,6 +8,12 @@
   was never entitled to do, so Safari and Chromium tabs were quietly never
   matched no matter how the setting was left.
 
+### Changed
+- The app now opens straight from the download, with no right-click or
+  Terminal command to get past macOS. Releases are signed and notarized, and
+  they keep the hardened runtime fully intact: the shipped build no longer has
+  to make an exception for loading the updater.
+
 ## v2026-06-30.1
 
 ### Added

RELEASING.md

@@ -1,9 +1,9 @@
 # Releasing
 
-The recommended way to install the app is to build it from source (see the
-README). A pre-built binary can be attached to a GitHub Release, but without an
-Apple Developer ID certificate it is ad-hoc signed and not notarized, so it has
-to be allowed through Gatekeeper by hand.
+Releases are signed with a Developer ID certificate and notarized by Apple, so
+the download opens without a Gatekeeper prompt. All of it happens in the
+`Release` workflow when a GitHub Release is published; the one-time credential
+setup is at the bottom of this file.
 
 Release tags use the format `vYYYY-MM-DD.X`, where `X` counts the releases made
 that day starting at 1 (for example `v2026-06-11.1`). The app's
@@ -20,22 +20,106 @@ valid in `CFBundleShortVersionString`.
    next sequence number (for example `v2026-06-11.1`), target `main`, and paste
    the changelog entries as the notes. Publishing it creates the tag.
 
-Publishing the Release triggers the `Release` workflow, which builds the
-artifact, attaches `PassQuickAccess.zip` to that same Release, signs it with the
+Publishing the Release triggers the `Release` workflow, which signs and notarizes
+the build, attaches `PassQuickAccess.zip` to that same Release, signs it with the
 Sparkle EdDSA key, and publishes the new version to `docs/appcast.xml` (served by
 GitHub Pages). The release notes you wrote become the changelog the app shows.
-To build the zip locally instead:
+
+The job refuses to run if the signing or notarization secrets are missing, rather
+than quietly publishing an ad-hoc build that every user would have to right-click
+past.
+
+## Dry run
+
+The same workflow can be started by hand from the Actions tab (*Run workflow*).
+It builds, signs and notarizes exactly as a real release does, but skips the two
+steps that publish: nothing is attached to a release and nothing is pushed to
+`main`. The Sparkle signing step still runs, so a dry run exercises every secret.
+
+This is the only way to find out whether the credentials work without cutting a
+release and watching it fail, so run it after changing any of them, and after
+touching the workflow or the build script.
+
+## Building locally
+
+`scripts/build-release.sh` does the whole artifact: build, signature check, zip,
+notarize, staple, re-zip, and a final Gatekeeper assessment. It is the same
+script CI runs, so a local build is the real thing rather than an approximation.
+
+```sh
+./scripts/build-release.sh
+```
+
+With nothing configured that builds ad-hoc and warns that the result is not
+distributable, which is fine for testing a Release build. To produce a signed,
+notarized zip:
 
 ```sh
+export PQA_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
+export PQA_TEAM_ID="TEAMID"
+export NOTARY_KEYCHAIN_PROFILE="NOTARY"
 ./scripts/build-release.sh
 ```
 
-This writes `dist/PassQuickAccess.zip`.
+`security find-identity -v -p codesigning` prints the identity string to use. The
+notarization profile is created once with:
+
+```sh
+xcrun notarytool store-credentials NOTARY \
+    --key ~/private_keys/AuthKey_XXXXXXXXXX.p8 \
+    --key-id XXXXXXXXXX --issuer 00000000-0000-0000-0000-000000000000
+```
+
+Either way it writes `dist/PassQuickAccess.zip`.
+
+## Signing and notarization (one-time setup)
+
+### 1. Developer ID Application certificate
+
+In Xcode, *Settings → Accounts → Manage Certificates → + → Developer ID
+Application*, or create it in the Apple Developer portal under *Certificates,
+Identifiers & Profiles*. Note that Apple allows a limited number of Developer ID
+certificates per account and they cannot be revoked casually, so keep the export
+below somewhere safe: losing it means asking Apple to reset.
+
+Export it from Keychain Access (the certificate together with its private key) as
+a `.p12` with a strong password, then load both into the repository:
+
+```sh
+base64 -i DeveloperID.p12 | gh secret set MACOS_CERTIFICATE_P12
+gh secret set MACOS_CERTIFICATE_PASSWORD
+gh secret set MACOS_SIGN_IDENTITY   # "Developer ID Application: Your Name (TEAMID)"
+gh secret set APPLE_TEAM_ID         # TEAMID
+```
+
+Delete the `.p12` from disk afterwards, or move it into your password manager.
+
+### 2. App Store Connect API key for notarization
+
+An API key is preferred over an app-specific password: it is scoped to a role, it
+can be revoked on its own without touching the Apple ID, and it never exposes
+account credentials to CI. In App Store Connect, *Users and Access → Integrations
+→ App Store Connect API*, create a key with the **Developer** role. The `.p8`
+downloads once and cannot be downloaded again.
+
+```sh
+gh secret set APPLE_API_KEY_P8 < AuthKey_XXXXXXXXXX.p8
+gh secret set APPLE_API_KEY_ID      # the key ID, e.g. XXXXXXXXXX
+gh secret set APPLE_API_ISSUER_ID   # the issuer UUID shown above the key list
+```
+
+### 3. What the workflow does with them
+
+The certificate is imported into a keychain created for the job and deleted when
+it ends, and the `.p8` is written outside the workspace and removed on the way
+out. Neither is ever placed in the built artifact. The workflow only runs on a
+published release, never from a pull request, so a fork cannot reach the secrets.
 
 ## Sparkle update signing (one-time setup)
 
 The app updates itself through [Sparkle](https://sparkle-project.org), and every
-update is verified against an EdDSA key. Set this up once:
+update is verified against an EdDSA key, independently of Apple's notarization.
+Set this up once:
 
 1. Generate the key pair with Sparkle's tool (it stores the private key in your
    login Keychain and prints the public key):
@@ -65,24 +149,52 @@ user picks "Update Now" (see [SECURITY.md](SECURITY.md)).
 release as an upgrade. `MARKETING_VERSION` is still the human version you bump in
 `project.yml`.
 
-## Installing an ad-hoc build
+## Entitlements
 
-A downloaded ad-hoc app is quarantined. The user opens it once with right-click
-to "Open", or clears the quarantine attribute:
+There are two entitlement files, and which one is used follows the signing mode:
 
-```sh
-xattr -dr com.apple.quarantine /Applications/PassQuickAccess.app
-```
+- `PassQuickAccess-Distribution.entitlements` for a Developer ID build, selected
+  by `build-release.sh` when `PQA_SIGN_IDENTITY` is set.
+- `PassQuickAccess.entitlements` everywhere else (development, ad-hoc), which
+  additionally disables library validation.
+
+The switch is the `PQA_ENTITLEMENTS_SUFFIX` variable, interpolated into
+`CODE_SIGN_ENTITLEMENTS` on the app target in `project.yml`. Overriding the path
+itself on the `xcodebuild` command line does not work: a command-line setting
+applies to every target, so the SPM packages inherit it and fail the build
+looking for the file inside their own checkout.
+
+The exemption exists because Xcode re-signs the embedded Sparkle.framework with
+the app's own identity: under a Developer ID both carry the same team and library
+validation passes, while an ad-hoc signature has no team for anything to match
+and the app would crash at launch. A shipped build therefore keeps the hardened
+runtime intact.
 
-## Notarized releases
+## Upgrading from an ad-hoc build
 
-Once an Apple Developer ID Application certificate is available, sign the Release
-build with it (set it in `Config/Local.xcconfig`), enable the hardened runtime,
-then notarize and staple:
+Releases up to and including `v2026-06-30.1` were ad-hoc signed, so the first
+signed release is the one update where the app's code signing identity changes
+underneath an existing install. The EdDSA key is unchanged, but Sparkle also
+compares the incoming build's signature against the running app's, and how it
+treats ad-hoc as the starting point is not obvious from the outside.
+
+This was tested before the first signed release, against a local appcast signed
+with the real EdDSA key: an ad-hoc build updated itself to a Developer ID signed
+one and came back with the new team identifier. **Sparkle accepts the
+transition**, so existing installs update themselves with nothing to announce.
+
+Worth redoing if the signing identity ever changes again, since it is the same
+question in a new form. The harness is three parts: an ad-hoc build whose
+`SUFeedURL` is repointed at a local server (which breaks its seal, so re-sign the
+bundle ad-hoc afterwards), a Developer ID build with a much higher
+`CFBundleVersion`, and an appcast signed with `sign_update`. Note that a build
+that is signed but not notarized can still be refused at relaunch by Gatekeeper,
+which looks like a Sparkle failure and is not one.
+
+Anyone still holding an old ad-hoc build can also just download the new one.
+Those older builds are quarantined until opened once with right-click → *Open*,
+or cleared with:
 
 ```sh
-xcrun notarytool submit dist/PassQuickAccess.zip --keychain-profile NOTARY --wait
-xcrun stapler staple dist/dd/Build/Products/Release/PassQuickAccess.app
+xattr -dr com.apple.quarantine /Applications/PassQuickAccess.app
 ```
-
-A notarized, stapled build opens without the Gatekeeper prompt.

SECURITY.md

@@ -16,9 +16,16 @@ Nothing is written to disk by the app.
 
 The trust boundary is the `pass-cli` session: anyone able to run code as your
 user can read your vault through the CLI directly, so the app's goal is to never
-be a weaker link than the CLI already is. Signed release builds use the hardened
-runtime without `get-task-allow`. The optional Touch ID lock guards casual
-access to an unlocked Mac, not local code execution.
+be a weaker link than the CLI already is. The optional Touch ID lock guards
+casual access to an unlocked Mac, not local code execution.
+
+Released builds are signed with a Developer ID certificate and notarized by
+Apple. They run under the hardened runtime with `get-task-allow` left out, so
+another process cannot attach to the app, and with library validation on, so the
+app loads no code signed by anyone else. A build made from source without a
+certificate is ad-hoc signed and has to relax library validation, because an
+ad-hoc signature carries no team identifier for the embedded Sparkle framework to
+match; that is the only difference between the two.
 
 See the security model section of the [README](README.md) for more detail.
 
@@ -37,10 +44,11 @@ Nothing installs on its own. When a newer version exists the app shows a small
 "Update" pill and waits; it downloads and replaces the app only after you pick
 "Update Now". Every update is verified against an ed25519 (EdDSA) public key
 pinned inside the app before it is allowed to install, so a tampered or
-intercepted download is rejected even though the build itself is not notarized.
-The private half of the signing key lives only in the maintainer's Keychain and a
-GitHub Actions secret, and the release workflow that uses it runs only when a
-maintainer publishes a release, never from a pull request.
+intercepted download is rejected. That check is Sparkle's own and is independent
+of Apple's notarization, which the download also carries: a forged update has to
+defeat both. The private half of the signing key lives only in the maintainer's
+Keychain and a GitHub Actions secret, and the release workflow that uses it runs
+only when a maintainer publishes a release, never from a pull request.
 
 ## Scope
 

Sources/PassQuickAccess/App/PassQuickAccess-Distribution.entitlements

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<!-- The entitlements of the signed, notarized build. Selected by
+	     scripts/build-release.sh when a Developer ID identity is configured;
+	     everything else uses PassQuickAccess.entitlements.
+
+	     The only difference is what is missing: this one does not disable
+	     library validation, so the hardened runtime will load nothing but code
+	     signed by the same team. That works here because Xcode re-signs the
+	     embedded Sparkle.framework, its XPC services and Updater.app with the
+	     app's identity, which an ad-hoc build has no team for. -->
+	<!-- Reads the active tab's URL from Safari and Chromium browsers, to
+	     pre-select the matching login. Under the hardened runtime an app may
+	     not send Apple events at all without this. -->
+	<key>com.apple.security.automation.apple-events</key>
+	<true/>
+</dict>
+</plist>