build: use an API key for macOS notarization

.github/CONTRIBUTING.md

@@ -37,6 +37,7 @@ Read it before opening a proposal; the licence check in particular ends most of
 
 - [Git](https://git-scm.com/)
 - `curl` (used by the Bun / uv / rustup install one-liners on macOS and Linux)
+- [Node.js 22](https://nodejs.org/) (Electron development and validation scripts)
 - [Bun](https://bun.sh/) (frontend package manager)
 - [uv](https://docs.astral.sh/uv/) (Python environment manager)
 - [ffmpeg](https://ffmpeg.org/) (audio/video processing)
@@ -174,6 +175,9 @@ Open an [issue](https://github.com/debpalash/VoiceStudio/issues/new) with:
 2. **Keep PRs focused** — one feature or fix per PR
 3. **Run tests** before pushing:
    ```bash
+   # Packaging tests use Electron dependencies, including electron-builder.
+   bun install --frozen-lockfile
+
    # Backend tests (the same two runs as CI; -n auto runs tests/ in parallel,
    # optional locally, it is about 4x faster on 4 cores)
    uv run pytest tests/ -q -n auto
@@ -313,6 +317,9 @@ disposing JSDOM. Keep deferred focus restoration in that same realm; advance
 only the current fake-timer tick rather than flushing unrelated future timers.
 
 ```bash
+# Packaging tests in tests/ load the installed Electron tooling.
+bun install --frozen-lockfile
+
 # Run the backend suites CI runs (kept separate: backend/tests is isolated)
 uv run pytest tests/ -q
 uv run pytest backend/tests/ -q

.github/workflows/ci.yml

@@ -208,6 +208,22 @@ jobs:
         # Backing off between whole attempts is what actually clears it.
         run: bash scripts/uv-sync-retry.sh --all-extras
 
+      # Cache ~/.bun/install/cache keyed on bun.lock — `bun install` drops
+      # from ~15 s cold to near-instant on warm cache.
+      - name: Cache bun deps
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install Electron deps
+        # --frozen-lockfile so an Electron workspace change that forgets to
+        # regenerate the root bun.lock fails HERE (fast) instead of only in the
+        # Docker build (deploy/Dockerfile), which is what reddened main on #485.
+        run: bun install --frozen-lockfile
+
       # HF_HUB_OFFLINE=1 is a recurrence guard, not an optimization: a test
       # that reaches huggingface.co fails fast and loud instead of silently
       # downloading model weights mid-suite (the preload_model() Hub-probe
@@ -233,24 +249,7 @@ jobs:
         env:
           HF_HUB_OFFLINE: "1"  # same no-silent-downloads guard as tests/
 
-      # Cache ~/.bun/install/cache keyed on bun.lock — `bun install` drops
-      # from ~15 s cold to near-instant on warm cache.
-      - name: Cache bun deps
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: ~/.bun/install/cache
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install Electron deps
-        # --frozen-lockfile so an Electron workspace change that forgets to
-        # regenerate the root bun.lock fails HERE (fast) instead of only in the
-        # Docker build (deploy/Dockerfile), which is what reddened main on #485.
-        run: bun install --frozen-lockfile
-
-      # Mobile theme tokens are generated from the Electron theme and need its
-      # deps installed, so the pytest copy of this check skips before this point.
+      # Check the generated mobile files explicitly as well as through pytest.
       - name: Mobile theme tokens match Electron
         run: bun --no-install scripts/export-mobile-tokens.ts --check
 

.github/workflows/electron-release.yml

@@ -197,22 +197,34 @@ jobs:
         run: bun install --frozen-lockfile
       - name: Validate and build Electron
         run: bun run check:electron
+      - name: Load notarization helper from workflow
+        if: matrix.platform == 'darwin'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api -H 'Accept: application/vnd.github.raw+json' \
+            "repos/$GITHUB_REPOSITORY/contents/scripts/prepare-apple-notarization.sh?ref=$GITHUB_SHA" \
+            > "$RUNNER_TEMP/prepare-apple-notarization.sh"
       - name: Package without publishing
         env:
           CSC_LINK: ${{ matrix.platform == 'darwin' && secrets.ELECTRON_MACOS_CSC_LINK || matrix.platform == 'win32' && secrets.ELECTRON_WINDOWS_CSC_LINK || '' }}
           CSC_KEY_PASSWORD: ${{ matrix.platform == 'darwin' && secrets.ELECTRON_MACOS_CSC_KEY_PASSWORD || matrix.platform == 'win32' && secrets.ELECTRON_WINDOWS_CSC_KEY_PASSWORD || '' }}
-          APPLE_ID: ${{ matrix.platform == 'darwin' && secrets.APPLE_ID || '' }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ matrix.platform == 'darwin' && secrets.APPLE_APP_SPECIFIC_PASSWORD || '' }}
-          APPLE_TEAM_ID: ${{ matrix.platform == 'darwin' && secrets.APPLE_TEAM_ID || '' }}
+          APPLE_API_KEY: ${{ matrix.platform == 'darwin' && secrets.APPLE_API_KEY || '' }}
+          APPLE_API_KEY_ID: ${{ matrix.platform == 'darwin' && secrets.APPLE_API_KEY_ID || '' }}
+          APPLE_API_ISSUER: ${{ matrix.platform == 'darwin' && secrets.APPLE_API_ISSUER || '' }}
           PUBLISH: ${{ inputs.publish }}
           ALLOW_UNSIGNED: ${{ inputs.allow_unsigned }}
         working-directory: electron
         run: |
           if [ "${{ matrix.platform }}" = darwin ] && [ "$PUBLISH" = true ] && [ "$ALLOW_UNSIGNED" != true ]; then
-            if [ -z "${CSC_LINK:-}" ] || [ -z "${CSC_KEY_PASSWORD:-}" ] || [ -z "${APPLE_ID:-}" ] || [ -z "${APPLE_APP_SPECIFIC_PASSWORD:-}" ] || [ -z "${APPLE_TEAM_ID:-}" ]; then
+            if [ -z "${CSC_LINK:-}" ] || [ -z "${CSC_KEY_PASSWORD:-}" ] || [ -z "${APPLE_API_KEY:-}" ] || [ -z "${APPLE_API_KEY_ID:-}" ] || [ -z "${APPLE_API_ISSUER:-}" ]; then
               echo "Signed macOS publication requires Developer ID and Apple notarization credentials"; exit 1
             fi
           fi
+          mac_notarization_args=()
+          if [ "${{ matrix.platform }}" = darwin ]; then
+            source "$RUNNER_TEMP/prepare-apple-notarization.sh"
+          fi
           # An empty CSC_LINK is interpreted as the working directory by the
           # signer. Omit absent credentials rather than passing empty strings.
           if [ -z "${CSC_LINK:-}" ]; then
@@ -227,7 +239,7 @@ jobs:
           # succeeded (error 68, v0.5.7-beta.2); only that failure builds again.
           set -o pipefail
           attempt=1
-          until bun x electron-builder --config electron-builder.config.mjs ${{ matrix.flags }} --publish never 2>&1 | tee "$RUNNER_TEMP/electron-builder.log"; do
+          until bun x electron-builder --config electron-builder.config.mjs ${{ matrix.flags }} "${mac_notarization_args[@]}" --publish never 2>&1 | tee "$RUNNER_TEMP/electron-builder.log"; do
             if [ "$attempt" -ge 2 ] || ! grep -q "Failed to staple" "$RUNNER_TEMP/electron-builder.log"; then exit 1; fi
             attempt=$((attempt + 1))
             echo "::warning::Stapling the notarization ticket failed; building again"

changelog.d/3775.changed.md

@@ -0,0 +1 @@
+Mac releases use an Apple API key for notarization instead of an account password. (#3775) — thanks @velixio!

docs/RELEASING.md

@@ -44,8 +44,11 @@ Electron publication uses these GitHub Actions secrets:
   `ELECTRON_MAC_APP_STORE_PROVISIONING_PROFILE` for private MAS packaging.
   These are separate from Developer ID credentials and do not authorize upload
   or publication.
-- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD` (not the Apple ID login password)
-  and `APPLE_TEAM_ID` for macOS notarization and stapling.
+- `APPLE_API_KEY` (raw `.p8` PEM text), `APPLE_API_KEY_ID` and
+  `APPLE_API_ISSUER` for macOS notarization and stapling. Use an App Store
+  Connect team key with Developer access. The packaging step writes the key
+  into a private temporary file and removes it on success or failure. Apple
+  ID passwords are not used by this workflow.
 - `ELECTRON_WINDOWS_CSC_LINK` and `ELECTRON_WINDOWS_CSC_KEY_PASSWORD` for
   Windows Authenticode signing. The macOS certificate cannot sign Windows apps.
 - `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_ISSUER_ID` and

docs/install/macos.md

@@ -105,11 +105,12 @@ Gatekeeper, and neither means the download is broken:
 - **"VoiceStudio cannot be opened because the developer cannot be verified"**:
   the milder form of the same check, which offers an Open path.
 
-Release builds are not notarized yet because that needs signing secrets the
-public release CI does not hold (tracked in #1779). Some builds are signed ad
-hoc (`identity: '-'`), which is not an Apple identity. Environments that forbid
-the workarounds below need a signed, notarized release; bypassing Gatekeeper is
-not a substitute.
+The release workflow requires Developer ID signing and notarization unless an
+unsigned release is explicitly approved. Older releases and local test builds
+may be signed ad hoc (`identity: '-'`), which is not an Apple identity. Check
+the signing status for the specific release you downloaded. Environments that
+require signed, notarized apps must use a qualifying release; bypassing
+Gatekeeper is not a substitute.
 
 **Check the download first.** Compute its SHA-256 and compare it with
 `SHA256SUMS.txt` from the same GitHub Release:
@@ -152,9 +153,8 @@ Anyway"**. You confirm once per install; later launches work by double-click.
 
 The maintained Electron release workflow uses a Developer ID Application
 certificate (`ELECTRON_MACOS_CSC_LINK` and `ELECTRON_MACOS_CSC_KEY_PASSWORD`)
-plus `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD` and `APPLE_TEAM_ID` for
-notarization. The Apple password is an **app-specific password**, not the
-account login password. See [the release guide](../RELEASING.md#credentials)
+plus `APPLE_API_KEY`, `APPLE_API_KEY_ID` and `APPLE_API_ISSUER` for
+notarization with an App Store Connect team API key. See [the release guide](../RELEASING.md#credentials)
 for all platform credentials and verification gates. An Apple Developer
 membership is required; the archived Tauri workflow's `APPLE_CERTIFICATE`
 secrets do not sign Electron installers.

docs/macos-signing-verification.md

@@ -10,7 +10,7 @@ acceptance. Credentials and the release procedure live in
 `electron-release.yml` packages macOS with electron-builder. When the
 Developer ID certificate (`ELECTRON_MACOS_CSC_LINK`,
 `ELECTRON_MACOS_CSC_KEY_PASSWORD`) and Apple notarization credentials
-(`APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`) are all present,
+(`APPLE_API_KEY`, `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`) are all present,
 the build enables Hardened Runtime and notarization together
 (`electron/electron-builder.config.mjs`). A publishing run refuses missing
 credentials unless the owner explicitly sets `allow_unsigned=true`, and before
@@ -67,8 +67,18 @@ scripts/verify-macos-signing.sh "VoiceStudio.app" --require-signed
 ```
 
 `xcrun notarytool history` runs when credentials are present in the environment
-(`NOTARYTOOL_KEYCHAIN_PROFILE`, or `APPLE_ID` + `APPLE_PASSWORD` +
-`APPLE_TEAM_ID`); otherwise it is skipped with a note.
+(`NOTARYTOOL_KEYCHAIN_PROFILE`, or `APPLE_API_KEY` + `APPLE_API_KEY_ID` +
+`APPLE_API_ISSUER`); otherwise it is skipped with a note.
+
+For local packaging and verification, `APPLE_API_KEY` is the path to the `.p8`
+file. In GitHub Secrets, it is the PEM file content; the workflow prepares the
+path before invoking electron-builder. The API key authenticates notarization;
+the Developer ID certificate and its password still sign the application.
+
+The packaging workflow loads key preparation from its own commit, even when
+checking out an older release tag. With complete certificate/API credentials,
+it explicitly enables notarization and Hardened Runtime in electron-builder,
+so older password-based configuration cannot silently skip notarization.
 
 ## Local development
 

electron/electron-builder.config.mjs

@@ -129,9 +129,9 @@ const notarizeMac =
   Boolean(
     process.env.CSC_LINK &&
     process.env.CSC_KEY_PASSWORD &&
-    process.env.APPLE_ID &&
-    process.env.APPLE_APP_SPECIFIC_PASSWORD &&
-    process.env.APPLE_TEAM_ID,
+    process.env.APPLE_API_KEY &&
+    process.env.APPLE_API_KEY_ID &&
+    process.env.APPLE_API_ISSUER,
   );
 
 // electron-builder never signs ad hoc on its own when no certificate exists, so

scripts/prepare-apple-notarization.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Source in the packaging step: GitHub stores PEM text, electron-builder needs a path.
+# Password credentials take precedence inside electron-builder; never inherit them.
+set +x
+unset APPLE_ID APPLE_APP_SPECIFIC_PASSWORD
+if [ -n "${APPLE_API_KEY:-}${APPLE_API_KEY_ID:-}${APPLE_API_ISSUER:-}" ]; then
+  for name in APPLE_API_KEY APPLE_API_KEY_ID APPLE_API_ISSUER; do
+    if [ -z "${!name:-}" ]; then
+      echo "::error::Notarization API credentials are incomplete: $name is missing" >&2
+      return 1
+    fi
+  done
+  : "${RUNNER_TEMP:?RUNNER_TEMP must identify the job temporary directory}"
+  NOTARY_KEY_DIR="$(mktemp -d "$RUNNER_TEMP/apple-notary.XXXXXX")"
+  trap 'rm -rf -- "$NOTARY_KEY_DIR"' EXIT
+  (umask 077; printf '%s' "$APPLE_API_KEY" > "$NOTARY_KEY_DIR/AuthKey.p8")
+  export APPLE_API_KEY="$NOTARY_KEY_DIR/AuthKey.p8"
+  if [ -n "${CSC_LINK:-}" ] && [ -n "${CSC_KEY_PASSWORD:-}" ]; then
+    # Older tag configs derive these from Apple password variables. Override
+    # them through electron-builder so rebuilding a tag still notarizes by API.
+    mac_notarization_args=(--config.mac.notarize=true --config.mac.hardenedRuntime=true)
+  fi
+fi

scripts/release.py

@@ -47,7 +47,7 @@
 SIGNING_ENV_NAMES = {
     "macOS": (
         "ELECTRON_MACOS_CSC_LINK", "ELECTRON_MACOS_CSC_KEY_PASSWORD",
-        "APPLE_ID", "APPLE_APP_SPECIFIC_PASSWORD", "APPLE_TEAM_ID",
+        "APPLE_API_KEY", "APPLE_API_KEY_ID", "APPLE_API_ISSUER",
     ),
     "Windows": ("ELECTRON_WINDOWS_CSC_LINK", "ELECTRON_WINDOWS_CSC_KEY_PASSWORD"),
 }

scripts/verify-macos-signing.sh

@@ -169,10 +169,10 @@ fi
 echo "[5/6] xcrun notarytool history  (audit log, opt-in)"
 if command -v xcrun >/dev/null 2>&1 && [ -n "${NOTARYTOOL_KEYCHAIN_PROFILE:-}" ]; then
   xcrun notarytool history --keychain-profile "$NOTARYTOOL_KEYCHAIN_PROFILE" 2>&1 | head -20 | sed 's/^/      /' || true
-elif command -v xcrun >/dev/null 2>&1 && [ -n "${APPLE_ID:-}" ] && [ -n "${APPLE_PASSWORD:-}" ] && [ -n "${APPLE_TEAM_ID:-}" ]; then
-  xcrun notarytool history --apple-id "$APPLE_ID" --password "$APPLE_PASSWORD" --team-id "$APPLE_TEAM_ID" 2>&1 | head -20 | sed 's/^/      /' || true
+elif command -v xcrun >/dev/null 2>&1 && [ -n "${APPLE_API_KEY:-}" ] && [ -n "${APPLE_API_KEY_ID:-}" ] && [ -n "${APPLE_API_ISSUER:-}" ]; then
+  xcrun notarytool history --key "$APPLE_API_KEY" --key-id "$APPLE_API_KEY_ID" --issuer "$APPLE_API_ISSUER" 2>&1 | head -20 | sed 's/^/      /' || true
 else
-  echo "      no notarization credentials in env (NOTARYTOOL_KEYCHAIN_PROFILE or APPLE_ID/APPLE_PASSWORD/APPLE_TEAM_ID) — skipping audit log"
+  echo "      no notarization credentials in env (NOTARYTOOL_KEYCHAIN_PROFILE or APPLE_API_KEY/APPLE_API_KEY_ID/APPLE_API_ISSUER) — skipping audit log"
 fi
 
 # ── 6. Quarantine attribute (informational) ───────────────────────────────

tests/test_ci_pytest_parallel.py

@@ -9,6 +9,8 @@
 import tomllib
 from pathlib import Path
 
+import yaml
+
 ROOT = Path(__file__).resolve().parents[1]
 
 
@@ -26,3 +28,14 @@ def test_backend_suite_stays_serial_until_its_order_dependence_is_fixed():
     workflow = (ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8")
     line = next(l for l in workflow.splitlines() if "pytest backend/tests/" in l)
     assert " -n " not in line
+
+
+def test_python_suite_installs_electron_dependencies_before_packaging_tests():
+    workflow = yaml.safe_load((ROOT / ".github/workflows/ci.yml").read_text(encoding="utf-8"))
+    steps = workflow["jobs"]["test-python"]["steps"]
+    install = next(i for i, step in enumerate(steps)
+                   if step.get("run") == "bun install --frozen-lockfile")
+    pytest = next(i for i, step in enumerate(steps)
+                  if "pytest tests/" in step.get("run", ""))
+    assert install < pytest, "Packaging regressions load the installed electron-builder during pytest"
+    assert "if" not in steps[install], "A clean runner must always install Electron dependencies"

tests/test_electron_transition.py

@@ -254,20 +254,23 @@ def test_electron_release_scopes_signing_secrets_and_gates_unsigned_owner_dispat
 ])
 def test_packaging_omits_empty_signing_credentials(tmp_path, credentials, expected):
     import os
+    import shutil
     import subprocess
     import yaml
+    shutil.copy(ROOT / 'scripts/prepare-apple-notarization.sh', tmp_path)
     workflow = yaml.load((ROOT / '.github/workflows/electron-release.yml').read_text(), Loader=yaml.BaseLoader)
     step = next(s for s in workflow['jobs']['package']['steps'] if s.get('name') == 'Package without publishing')
     for name, body in [('bun', 'printf "%s|%s" "${CSC_LINK+x}" "${CSC_KEY_PASSWORD+x}" > "$CAPTURE_PATH"'), ('node', 'exit 0')]:
         executable = tmp_path / name
         executable.write_text('#!/bin/sh\n' + body + '\n')
         executable.chmod(0o755)
-    env = {k: v for k, v in os.environ.items() if k not in {'CSC_LINK', 'CSC_KEY_PASSWORD'}}
+    env = {k: v for k, v in os.environ.items() if not k.startswith(('CSC_', 'APPLE_'))}
     env.update(credentials)
     capture = tmp_path / 'signing-env'
-    env.update(PATH=str(tmp_path) + os.pathsep + env['PATH'], CAPTURE_PATH=str(capture), RUNNER_TEMP=str(tmp_path))
+    env.update(PATH=str(tmp_path) + os.pathsep + env['PATH'], CAPTURE_PATH=str(capture),
+               RUNNER_TEMP=str(tmp_path), RUNNER_OS='macOS', PUBLISH='false')
     script = step['run'].replace('${{ matrix.flags }}', '--mac --arm64').replace('${{ matrix.platform }}', 'darwin').replace('${{ matrix.arch }}', 'arm64')
-    subprocess.run(['bash', '-e', '-c', script], env=env, check=True)
+    subprocess.run(['bash', '-e', '-c', script], cwd=ROOT / 'electron', env=env, check=True)
     assert capture.read_text() == expected