[iLevyTate]

Summary

• With APPLE_* credentials set, electron-builder notarizes the signed .app right after codesigning, in one attempt. A dropped connection to Apple's notary service then fails the whole build. The macOS x64 jobs for 5.1.0 (NSURLErrorDomain -1005 while stapling) and 5.1.1 (-1009 while waiting on the submission) both died there. The retries from ci(mac-release): retry Apple notary and stapler network calls #46 only cover the workflow's later dmg/zip notarization.
• electron-builder.json now sets mac.notarize: false and names an afterSign hook, scripts/notarize-mac-app.js. The hook runs at the same point (after codesigning, before the dmg and zip are built) and makes the same @electron/notarize call with the same credentials. It tries up to three times, 30 s and 60 s apart.
• Same behaviour otherwise:
  • The hook loads app-builder-lib's own @electron/notarize (2.5.0), the copy electron-builder uses. The top-level 3.x is ESM-only and needs Node 22.12, but the release runners use Node 20.
  • It mirrors MacTargetHelper.getNotarizeOptions: Apple ID, API key or keychain profile, with the same errors.
  • It does nothing for Windows, Linux and Mac App Store builds, or without credentials.
• docs/MAC_SIGNING.md describes the hook in the workflow walkthrough.

Scope

• Area(s): macOS release (electron-builder config, afterSign hook)
• Risk Level: medium. It changes how the signed macOS app gets notarized. The call and its options are identical, but only a release run proves it.
• Breaking Changes: none

Type of Change

• Bug fix
• Enhancement
• New feature
• Refactor
• Documentation update
• Breaking change

Test Plan

Automated

• npm run format:check (Prettier on the changed files)
• npm run lint (ESLint on the hook and its test)
• npm test: notarizeMacApp, electron-builder-config, verifyElectronFusesConfig, verifyPackagedArtifacts (all pass), knip:files, and compliance:commercial:verify (inventory unchanged)
• Additional tests added/updated when behavior changed

test/notarizeMacApp.test.js covers:

• the hook's options and errors against electron-builder's own getNotarizeOptions, for 8 credential cases
• the retry, backoff and give-up paths
• skipping non-darwin builds and builds without credentials
• that electron-builder's resolveFunction loads the configured hook as afterSign (this check fails if the export is removed)

Manual QA

• Manual checklist completed (see docs/TESTING.md)
• Not applicable (explain below)

Manual QA notes:

• Notarization needs Apple credentials and a macOS runner, so the next mac-release.yml run is the real test. The log should show [notarize] StratoSort Stack.app notarized and stapled in the signed build step.

Checklist

• I scoped this PR to one logical change
• I self-reviewed code and naming for clarity
• I updated docs/config references where needed
• I called out follow-up work or known limitations: the 5.1.1 macOS x64 job is being re-run on the old flow; this applies from the next release.

---

Generated by Claude Code