Sign and notarize macOS app in CI

Import the Developer ID cert into a temporary keychain in build-macos.yml,
switch the package step from --no-sign to --notarize, and add credential-based
notarization to package-macos.sh (NOTARY_APPLE_ID/PASSWORD/TEAM_ID env vars)
for the CI case where no local keychain profile exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: StuartCameronCode

.github/workflows/build-macos.yml

@@ -149,15 +149,62 @@ jobs:
           mkdir -p ../build/macos/Build/Products/Release
           cp -R "$DERIVED_APP" ../build/macos/Build/Products/Release/
 
+      - name: Import Developer ID certificate
+        env:
+          MACOS_CERTIFICATE: ${{ secrets.MACOS_CERTIFICATE }}
+          MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+          MACOS_KEYCHAIN_PASSWORD: ${{ secrets.MACOS_KEYCHAIN_PASSWORD }}
+        run: |
+          KEYCHAIN_PATH="$RUNNER_TEMP/app-signing.keychain-db"
+          CERT_PATH="$RUNNER_TEMP/developer-id.p12"
+
+          echo "$MACOS_CERTIFICATE" | base64 --decode > "$CERT_PATH"
+
+          # Create a dedicated, unlocked keychain just for this build
+          security create-keychain -p "$MACOS_KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$MACOS_KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Import the Developer ID Application cert + private key
+          security import "$CERT_PATH" -P "$MACOS_CERTIFICATE_PASSWORD" \
+            -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
+
+          # Allow codesign to use the key without an interactive prompt
+          security set-key-partition-list -S apple-tool:,apple:,codesign: \
+            -s -k "$MACOS_KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
+
+          # Make this keychain the default + only one in the search list so
+          # package-macos.sh's `security find-identity` resolves the identity
+          security list-keychains -d user -s "$KEYCHAIN_PATH"
+          security default-keychain -s "$KEYCHAIN_PATH"
+
+          rm -f "$CERT_PATH"
+
+          echo "Signing identities available:"
+          security find-identity -v -p codesigning "$KEYCHAIN_PATH"
+
       - name: Package release (arm64)
         if: ${{ inputs.arch == 'arm64' || inputs.arch == 'both' }}
+        env:
+          NOTARY_APPLE_ID: ${{ secrets.MACOS_NOTARY_APPLE_ID }}
+          NOTARY_PASSWORD: ${{ secrets.MACOS_NOTARY_PASSWORD }}
+          NOTARY_TEAM_ID: ${{ secrets.MACOS_NOTARY_TEAM_ID }}
         run: |
-          ./Scripts/package-macos.sh --version "${{ inputs.version }}" --arch arm64 --skip-build --no-sign
+          ./Scripts/package-macos.sh --version "${{ inputs.version }}" --arch arm64 --skip-build --notarize
 
       - name: Package release (x64)
         if: ${{ inputs.arch == 'x64' || inputs.arch == 'both' }}
+        env:
+          NOTARY_APPLE_ID: ${{ secrets.MACOS_NOTARY_APPLE_ID }}
+          NOTARY_PASSWORD: ${{ secrets.MACOS_NOTARY_PASSWORD }}
+          NOTARY_TEAM_ID: ${{ secrets.MACOS_NOTARY_TEAM_ID }}
+        run: |
+          ./Scripts/package-macos.sh --version "${{ inputs.version }}" --arch x64 --skip-build --notarize
+
+      - name: Clean up signing keychain
+        if: always()
         run: |
-          ./Scripts/package-macos.sh --version "${{ inputs.version }}" --arch x64 --skip-build --no-sign
+          security delete-keychain "$RUNNER_TEMP/app-signing.keychain-db" 2>/dev/null || true
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4

CLAUDE.md

@@ -490,11 +490,45 @@ Prerequisites: draft release must exist for the tag, `gh` CLI authenticated.
 5. **Test** — fresh install + upgrade test
 6. **Create GitHub releases** — deps release first (if changed, tag `deps-vX.Y.Z`), then app release (tag `vX.Y.Z`)
 
+### macOS Code Signing & Notarization
+
+The macOS app is signed with a **Developer ID Application** certificate and notarized by Apple so it launches without Gatekeeper warnings. Signing happens **in CI** (`build-macos.yml`) — the runner imports the cert into a temporary keychain, then `package-macos.sh --notarize` signs every Mach-O inner-out (dylibs → frameworks → `.so` → worker → app), signs the DMG, submits to the notary service, and staples the ticket. `ci-build-and-release.sh` just downloads the finished signed/notarized DMG and uploads it — no local signing step.
+
+`package-macos.sh` also works locally: with a Developer ID cert in your keychain it signs, and `--notarize` uses a stored `notarytool` keychain profile (default name `VapourBox`). In CI there is no keychain profile, so it falls back to `NOTARY_APPLE_ID` / `NOTARY_PASSWORD` / `NOTARY_TEAM_ID` env vars. Use `--no-sign` for ad-hoc local test builds.
+
+**Required GitHub repo secrets** (Settings → Secrets and variables → Actions):
+
+| Secret | Value |
+|--------|-------|
+| `MACOS_CERTIFICATE` | Base64 of the exported Developer ID Application `.p12` |
+| `MACOS_CERTIFICATE_PASSWORD` | Password set when exporting the `.p12` |
+| `MACOS_KEYCHAIN_PASSWORD` | Any random string (temp keychain password) |
+| `MACOS_NOTARY_APPLE_ID` | Apple ID email for notarization |
+| `MACOS_NOTARY_PASSWORD` | App-specific password from appleid.apple.com |
+| `MACOS_NOTARY_TEAM_ID` | `PMXZ63S6YG` |
+
+**One-time setup** (export the cert and load secrets via `gh`):
+
+```bash
+# 1. Export the Developer ID Application cert + private key from Keychain Access
+#    (right-click the identity → Export → .p12, set a password) to ~/devid.p12
+# 2. Base64-encode and store all secrets:
+gh secret set MACOS_CERTIFICATE < <(base64 -i ~/devid.p12)
+gh secret set MACOS_CERTIFICATE_PASSWORD   # paste the .p12 export password
+gh secret set MACOS_KEYCHAIN_PASSWORD      # paste any random string
+gh secret set MACOS_NOTARY_APPLE_ID        # paste your Apple ID email
+gh secret set MACOS_NOTARY_PASSWORD        # paste app-specific password
+gh secret set MACOS_NOTARY_TEAM_ID         # paste PMXZ63S6YG
+rm ~/devid.p12
+```
+
+Create the app-specific password at appleid.apple.com → Sign-In and Security → App-Specific Passwords. The Developer ID cert expires **2027-02-01**; re-export and update `MACOS_CERTIFICATE` before then.
+
 ### Cross-Platform Notes
 
 - Flutter Windows can't build on macOS — use GitHub Actions
 - Windows deps can be zipped on macOS if `deps/windows-x64/` exists
-- CI builds are ad-hoc signed; sign locally for distribution
+- The macOS CI build (`build-macos.yml`) signs with the Developer ID cert and notarizes — see "macOS Code Signing & Notarization" below. Windows CI builds remain unsigned.
 
 ### Dependency Version History
 

README.md

@@ -39,7 +39,7 @@ Get the latest release for your platform:
 2. Open the DMG and drag **VapourBox** to your Applications folder
 3. On first launch, VapourBox will automatically download its processing dependencies (~180 MB)
 
-> **Note**: You may need to right-click and choose "Open" the first time, since the app is not notarized.
+> **Note**: VapourBox is signed with an Apple Developer ID and notarized, so it opens normally — just drag it to Applications and launch.
 
 ### Windows
 

Scripts/package-macos.sh

@@ -368,9 +368,21 @@ if $NOTARIZE && ! $NO_SIGN; then
     echo "[$STEP/$TOTAL_STEPS] Notarizing with Apple..."
     echo "    Submitting to notary service (this may take several minutes)..."
 
-    xcrun notarytool submit "$DMG_FILE" \
-        --keychain-profile "$KEYCHAIN_PROFILE" \
-        --wait
+    # CI uses credentials passed via env vars (no local keychain profile exists on
+    # the runner); locally we fall back to a stored notarytool keychain profile.
+    if [ -n "$NOTARY_APPLE_ID" ] && [ -n "$NOTARY_PASSWORD" ]; then
+        echo "    Using Apple ID credentials from environment ($NOTARY_APPLE_ID)"
+        xcrun notarytool submit "$DMG_FILE" \
+            --apple-id "$NOTARY_APPLE_ID" \
+            --password "$NOTARY_PASSWORD" \
+            --team-id "${NOTARY_TEAM_ID:-$TEAM_ID}" \
+            --wait
+    else
+        echo "    Using notarytool keychain profile: $KEYCHAIN_PROFILE"
+        xcrun notarytool submit "$DMG_FILE" \
+            --keychain-profile "$KEYCHAIN_PROFILE" \
+            --wait
+    fi
 
     echo "    Stapling notarization ticket..."
     xcrun stapler staple "$DMG_FILE"