ci: switch notarization auth to App Store Connect API key, gate on environment

Two changes that significantly reduce the CI signing risk profile:

1. Replace --apple-id/--team-id/--password (app-specific password) with
   --key/--key-id/--issuer (App Store Connect API key). The API key is a
   service credential scoped to the developer team and a role - it cannot
   sign in to icloud.com or appleid.apple.com, cannot touch iCloud data
   or payment methods, and is independent of any personal Apple ID
   password. Apple recommends API keys over app-specific passwords for
   automation.

2. Bind the build job to a GitHub Environment named `release`. A tag
   push now pauses the workflow at the environment gate; the runner
   does not decrypt any signing material until a manually-approved
   reviewer clicks through. An accidental or attacker-pushed tag does
   not auto-release.

scripts/release-notarize.sh accepts both --key/--key-id/--issuer (used
by CI) and --keychain-profile NAME (recommended for local releases via
`xcrun notarytool store-credentials`), with strict validation that
exactly one auth mode is passed. Updated docs/releasing.md to cover the
new prerequisites, the Approve-deployment step, and a local-release
fallback that uses keychain-stored credentials.

Required repo secrets after this change:
  BUILD_CERTIFICATE_BASE64, P12_PASSWORD, KEYCHAIN_PASSWORD,
  SIGNING_IDENTITY, APP_STORE_CONNECT_KEY_BASE64,
  APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_ISSUER.
Removed: APPLE_ID, APPLE_TEAM_ID, APPLE_APP_SPECIFIC_PASSWORD.

Author: pszypowicz

.github/workflows/release.yml

@@ -7,13 +7,18 @@ name: Release
 #   P12_PASSWORD                    - password protecting the .p12
 #   KEYCHAIN_PASSWORD               - random string for the temporary keychain
 #   SIGNING_IDENTITY                - "Developer ID Application: Name (TEAMID)"
-#   APPLE_ID                        - Apple ID email used for notarization
-#   APPLE_TEAM_ID                   - 10-char Developer team identifier
-#   APPLE_APP_SPECIFIC_PASSWORD     - from appleid.apple.com
+#   APP_STORE_CONNECT_KEY_BASE64    - base64 of the .p8 App Store Connect API key
+#   APP_STORE_CONNECT_KEY_ID        - 10-char Key ID
+#   APP_STORE_CONNECT_ISSUER        - issuer UUID
 #
-# The published zip is built by ditto post-staple so the notarization
-# ticket travels with the archive and Gatekeeper accepts the bundle
-# offline on first launch.
+# Required GitHub Environment: `release`. The job binds to it so a tag push
+# pauses for manual approval before any signing material is decrypted on the
+# runner. Configure the environment at Settings -> Environments -> release
+# with required reviewer = the repo owner.
+#
+# The published zip is built by `zip -ry` post-staple so the notarization
+# ticket travels with the archive and Gatekeeper accepts the bundle offline
+# on first launch.
 
 on:
   push:
@@ -25,6 +30,7 @@ permissions:
 jobs:
   build:
     runs-on: macos-15
+    environment: release
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
         with:
@@ -52,6 +58,15 @@ jobs:
               -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH" >/dev/null
           rm -f "$CERT_PATH"
 
+      - name: Write App Store Connect API key
+        env:
+          APP_STORE_CONNECT_KEY_BASE64: ${{ secrets.APP_STORE_CONNECT_KEY_BASE64 }}
+        run: |
+          set -euo pipefail
+          KEY_PATH="$RUNNER_TEMP/AuthKey.p8"
+          echo "$APP_STORE_CONNECT_KEY_BASE64" | base64 --decode > "$KEY_PATH"
+          chmod 600 "$KEY_PATH"
+
       - name: Build, sign, and zip
         env:
           SIGNING_IDENTITY: ${{ secrets.SIGNING_IDENTITY }}
@@ -60,14 +75,13 @@ jobs:
 
       - name: Notarize, staple, and refresh zip
         env:
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APP_STORE_CONNECT_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
+          APP_STORE_CONNECT_ISSUER: ${{ secrets.APP_STORE_CONNECT_ISSUER }}
         run: |
           scripts/release-notarize.sh \
-              --apple-id "$APPLE_ID" \
-              --team-id "$APPLE_TEAM_ID" \
-              --password "$APPLE_APP_SPECIFIC_PASSWORD"
+              --key "$RUNNER_TEMP/AuthKey.p8" \
+              --key-id "$APP_STORE_CONNECT_KEY_ID" \
+              --issuer "$APP_STORE_CONNECT_ISSUER"
 
       - name: Verify signature and notarization
         run: |
@@ -81,10 +95,12 @@ jobs:
         with:
           files: .build/MicGuard.zip
 
-      - name: Clean up keychain
+      - name: Clean up secrets on runner
         if: always()
         run: |
           KEYCHAIN_PATH="$RUNNER_TEMP/build.keychain-db"
+          KEY_PATH="$RUNNER_TEMP/AuthKey.p8"
           if [[ -f "$KEYCHAIN_PATH" ]]; then
               security delete-keychain "$KEYCHAIN_PATH" || true
           fi
+          rm -f "$KEY_PATH"

docs/releasing.md

@@ -12,31 +12,49 @@ How to publish a new MicGuard version to Homebrew.
 
 The app version is derived from the latest git tag at build time. `scripts/bundle.sh` runs `git describe --tags` and stamps the result into `Info.plist` via `PlistBuddy`. The source `Info.plist` contains a `0.0.0-dev` placeholder — do not hardcode a version there.
 
+## Prerequisites
+
+The release workflow needs these one-time-setup repo secrets:
+
+- `BUILD_CERTIFICATE_BASE64` - base64 of the Developer ID Application `.p12`
+- `P12_PASSWORD` - password protecting the `.p12`
+- `KEYCHAIN_PASSWORD` - random string for the temporary runner keychain
+- `SIGNING_IDENTITY` - `Developer ID Application: <Name> (<TEAMID>)`
+- `APP_STORE_CONNECT_KEY_BASE64` - base64 of the `.p8` App Store Connect API key
+- `APP_STORE_CONNECT_KEY_ID` - 10-char Key ID
+- `APP_STORE_CONNECT_ISSUER` - issuer UUID
+
+Plus a GitHub Environment named `release` with required reviewer set to the repo owner. The workflow binds the build job to this environment, so a tag push pauses for manual approval before any signing material is decrypted on the runner.
+
 ## 1. Tag and push
 
 ```bash
 git tag v<version>
 git push origin v<version>
 ```
 
-GitHub Actions builds the app and creates a release with `MicGuard.zip`. The tag determines the version embedded in the built app.
+The `Release` workflow starts and pauses on the `release` environment, waiting for approval.
 
-## 2. Get the SHA-256
+## 2. Approve the deployment
+
+Open the workflow run on GitHub. The `build` job will be in `Waiting` state with a `Review deployments` button. Click it, select `release`, and approve. The job then imports the certificate, builds, signs, notarizes, staples, verifies, and publishes the release with `MicGuard.zip`.
+
+## 3. Get the SHA-256
 
 Once the release is published, compute the checksum:
 
 ```bash
 curl -sL https://github.com/pszypowicz/MicGuard/releases/download/v<version>/MicGuard.zip | shasum -a 256
 ```
 
-## 3. Update the Homebrew cask
+## 4. Update the Homebrew cask
 
 In the [`homebrew-tap`](https://github.com/pszypowicz/homebrew-tap) repo, edit `Casks/mic-guard.rb`:
 
 ```ruby
 cask "mic-guard" do
   version "<version>"
-  sha256 "<sha256 from step 2>"
+  sha256 "<sha256 from step 3>"
 
   url "https://github.com/pszypowicz/MicGuard/releases/download/v#{version}/MicGuard.zip"
   # ...
@@ -45,9 +63,30 @@ end
 
 Update both the `version` and `sha256` fields, then commit and push.
 
-## 4. Verify
+## 5. Verify
 
 ```bash
 brew update
 brew upgrade mic-guard
 ```
+
+## Local release (fallback)
+
+If the CI path is broken or you want to release from your Mac, use [`scripts/release-notarize.sh`](https://github.com/pszypowicz/MicGuard/blob/main/scripts/release-notarize.sh). One-time setup:
+
+```bash
+xcrun notarytool store-credentials MicGuard \
+    --key /path/to/AuthKey_XXXXXXXXXX.p8 \
+    --key-id XXXXXXXXXX \
+    --issuer YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
+```
+
+Per-release:
+
+```bash
+SIGNING_IDENTITY='Developer ID Application: <Name> (<TEAMID>)' \
+  ENTITLEMENTS=Resources/MicGuard.entitlements \
+  make zip
+scripts/release-notarize.sh --keychain-profile MicGuard
+gh release create v<version> .build/MicGuard.zip --generate-notes
+```

scripts/release-notarize.sh

@@ -4,73 +4,98 @@
 # resulting ticket onto the .app, and re-zip so the published archive ships
 # with offline-verifiable notarization.
 #
-# Inputs (named flags - positional args are not accepted):
-#   --app PATH          path to the signed .app bundle (default: .build/MicGuard.app)
-#   --zip PATH          path to the zip uploaded for notarization (default: .build/MicGuard.zip)
-#   --apple-id EMAIL    Apple ID used for notarization
-#   --team-id TEAM      10-char Apple Developer team identifier
-#   --password PWD      app-specific password (NOT the Apple ID account password)
-#   -h, --help          show usage and exit
+# Two authentication modes (pick one):
 #
-# Exit codes:
-#   0  notarized + stapled, zip refreshed
-#   1  notarization rejected by Apple, or stapler failed
-#   2  bad usage (missing flag, unknown flag)
+#   1. App Store Connect API key (recommended for CI):
+#        --key PATH --key-id ID --issuer UUID
+#
+#   2. Keychain profile (recommended for local: run
+#      `xcrun notarytool store-credentials NAME ...` once, then reference NAME):
+#        --keychain-profile NAME
 #
 # notarytool's --wait flag polls until Apple returns a terminal status, so
-# this script does not implement its own polling loop. Submission log is
+# this script does not implement its own polling loop. The submission log is
 # fetched on rejection so the failure reason ends up in CI output.
+#
+# Exit codes:
+#   0  notarized + stapled, zip refreshed
+#   1  notarization rejected by Apple, or stapler failed
+#   2  bad usage (missing/conflicting flags, file not found)
 
 set -euo pipefail
 
 usage() {
     cat <<'USAGE'
-Usage: release-notarize.sh --apple-id EMAIL --team-id TEAM --password PWD \
-                           [--app PATH] [--zip PATH]
+Usage:
+  release-notarize.sh --key PATH --key-id ID --issuer UUID [--app PATH] [--zip PATH]
+  release-notarize.sh --keychain-profile NAME            [--app PATH] [--zip PATH]
 
 Submit a signed .app/.zip to Apple notarization, staple the ticket, and
 refresh the zip so the published archive carries the notarization offline.
 
-Required flags:
-  --apple-id EMAIL    Apple ID used for notarization
-  --team-id TEAM      10-char Apple Developer team identifier
-  --password PWD      app-specific password (appleid.apple.com)
+Authentication (choose exactly one):
+  --key PATH                path to App Store Connect API key (.p8)
+  --key-id ID               10-char Key ID from App Store Connect
+  --issuer UUID             issuer UUID from App Store Connect
+  --keychain-profile NAME   profile name set up via `notarytool store-credentials`
+
+Optional:
+  --app PATH                path to the .app bundle (default: .build/MicGuard.app)
+  --zip PATH                path to the zip to submit (default: .build/MicGuard.zip)
+  -h, --help                show this help and exit
 
-Optional flags:
-  --app PATH          path to the .app bundle (default: .build/MicGuard.app)
-  --zip PATH          path to the zip to submit (default: .build/MicGuard.zip)
-  -h, --help          show this help and exit
+Examples:
+  # CI / explicit credentials
+  release-notarize.sh --key ./AuthKey_ABCDEF1234.p8 \
+      --key-id ABCDEF1234 --issuer 12345678-1234-1234-1234-123456789012
 
-Example:
-  release-notarize.sh --apple-id me@example.com --team-id ABCDE12345 \
-      --password "$APPLE_APP_SPECIFIC_PASSWORD"
+  # Local, after running `xcrun notarytool store-credentials MicGuard ...`
+  release-notarize.sh --keychain-profile MicGuard
 USAGE
 }
 
 APP=".build/MicGuard.app"
 ZIP=".build/MicGuard.zip"
-APPLE_ID=""
-TEAM_ID=""
-PASSWORD=""
+KEY=""
+KEY_ID=""
+ISSUER=""
+KEYCHAIN_PROFILE=""
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --app)       APP="$2"; shift 2 ;;
-        --zip)       ZIP="$2"; shift 2 ;;
-        --apple-id)  APPLE_ID="$2"; shift 2 ;;
-        --team-id)   TEAM_ID="$2"; shift 2 ;;
-        --password)  PASSWORD="$2"; shift 2 ;;
-        -h|--help)   usage; exit 0 ;;
-        *)           echo "error: unknown flag: $1" >&2; usage >&2; exit 2 ;;
+        --app)               APP="$2"; shift 2 ;;
+        --zip)               ZIP="$2"; shift 2 ;;
+        --key)               KEY="$2"; shift 2 ;;
+        --key-id)            KEY_ID="$2"; shift 2 ;;
+        --issuer)            ISSUER="$2"; shift 2 ;;
+        --keychain-profile)  KEYCHAIN_PROFILE="$2"; shift 2 ;;
+        -h|--help)           usage; exit 0 ;;
+        *)                   echo "error: unknown flag: $1" >&2; usage >&2; exit 2 ;;
     esac
 done
 
-missing=()
-[[ -z "$APPLE_ID" ]] && missing+=(--apple-id)
-[[ -z "$TEAM_ID"  ]] && missing+=(--team-id)
-[[ -z "$PASSWORD" ]] && missing+=(--password)
-if (( ${#missing[@]} > 0 )); then
-    echo "error: missing required flag(s): ${missing[*]}" >&2
+# Pick auth mode: keychain profile XOR (key + key-id + issuer).
+api_key_mode_count=0
+[[ -n "$KEY"     ]] && api_key_mode_count=$((api_key_mode_count + 1))
+[[ -n "$KEY_ID"  ]] && api_key_mode_count=$((api_key_mode_count + 1))
+[[ -n "$ISSUER"  ]] && api_key_mode_count=$((api_key_mode_count + 1))
+
+if [[ -n "$KEYCHAIN_PROFILE" ]]; then
+    if (( api_key_mode_count > 0 )); then
+        echo "error: --keychain-profile cannot be combined with --key/--key-id/--issuer" >&2
+        usage >&2
+        exit 2
+    fi
+    auth_args=(--keychain-profile "$KEYCHAIN_PROFILE")
+elif (( api_key_mode_count == 3 )); then
+    [[ -f "$KEY" ]] || { echo "error: API key not found: $KEY" >&2; exit 2; }
+    auth_args=(--key "$KEY" --key-id "$KEY_ID" --issuer "$ISSUER")
+elif (( api_key_mode_count == 0 )); then
+    echo "error: missing authentication; pass --keychain-profile NAME or all of --key/--key-id/--issuer" >&2
+    usage >&2
+    exit 2
+else
+    echo "error: --key, --key-id, and --issuer must be passed together" >&2
     usage >&2
     exit 2
 fi
@@ -83,9 +108,7 @@ submit_log=$(mktemp)
 trap 'rm -f "$submit_log"' EXIT
 
 if ! xcrun notarytool submit "$ZIP" \
-        --apple-id "$APPLE_ID" \
-        --team-id "$TEAM_ID" \
-        --password "$PASSWORD" \
+        "${auth_args[@]}" \
         --wait \
         --output-format plist \
         > "$submit_log"; then
@@ -94,9 +117,6 @@ if ! xcrun notarytool submit "$ZIP" \
     exit 1
 fi
 
-# Parse the submission ID + status from the plist output. PlistBuddy on macOS
-# is the standard tool for this; fall back to grep if PlistBuddy is missing
-# (notarytool always runs on macOS so PlistBuddy should be present).
 status=$(/usr/libexec/PlistBuddy -c "Print :status" "$submit_log" 2>/dev/null || echo "")
 submission_id=$(/usr/libexec/PlistBuddy -c "Print :id" "$submit_log" 2>/dev/null || echo "")
 
@@ -106,10 +126,7 @@ if [[ "$status" != "Accepted" ]]; then
     echo "error: notarization not accepted" >&2
     if [[ -n "$submission_id" ]]; then
         echo "==> fetching submission log:" >&2
-        xcrun notarytool log "$submission_id" \
-            --apple-id "$APPLE_ID" \
-            --team-id "$TEAM_ID" \
-            --password "$PASSWORD" >&2 || true
+        xcrun notarytool log "$submission_id" "${auth_args[@]}" >&2 || true
     fi
     exit 1
 fi