Desktop signing and distribution

Signing & Platform Distribution

Unsigned or improperly signed desktop applications trigger alarming OS gatekeeper blocks ("App is damaged and can't be opened" on macOS, SmartScreen warnings on Windows) and break auto-updaters (Squirrel.Mac / NSIS). Treat signing, entitlements, and platform metadata as core architecture requirements.

macOS Code Signing, Hardened Runtime & Notarization

1. Inside-Out Signing Order:
   • Every executable binary, .dylib, .node native addon, and embedded sidecar inside .app/Contents/Resources or .app/Contents/Frameworks must be signed with a valid Developer ID Application certificate and secure timestamp before signing the outer .app bundle. Modifying any file inside .app after signing invalidates the seal immediately.
2. Hardened Runtime & Minimal Entitlements (entitlements.mac.plist):
   • Apple notarization requires Hardened Runtime (--options runtime). Request only the entitlements your runtime genuinely needs:
     • Electron V8 JIT requires com.apple.security.cs.allow-jit (and helper renderer entitlements).
     • Loading unpacked third-party .node addons may require com.apple.security.cs.allow-unsigned-executable-memory or disable-library-validation (only when addons are not signed by the same Team ID).
   • Include clear NS*UsageDescription strings in Info.plist whenever accessing protected folders, microphone, camera, or automation events.
3. Notarization & Stapling (notarytool + stapler):
   • Submit the signed .dmg / .zip / .pkg to Apple's notarization service (xcrun notarytool submit --wait), inspect the JSON log on any rejection, and staple the ticket (xcrun stapler staple) to the .dmg/.app so Gatekeeper verification succeeds even when the user is offline.

Windows Authenticode, SmartScreen & Installer Formats

1. Authenticode Signing with Timestamp Server:
   • Sign both the inner application .exe (and any custom native .dll/sidecar binaries) and the outer installer (NSIS .exe, MSIX, or MSI) using SHA-256 (fd sha256) and an RFC 3161 timestamp server (tr http://timestamp.digicert.com).
2. Per-User vs. Per-Machine Installation Paths:
   • Default to per-user installation (%LOCALAPPDATA%\Programs\<App>) when seamless background auto-updates without UAC Administrator elevation prompts are desired, or document explicit UAC behavior for machine-wide (%ProgramFiles%) enterprise MSI/MSIX deployments.
3. Clean Uninstall & File Association Hygiene:
   • Register custom URL schemes (myapp://), PATH shims, and startup entries cleanly so uninstalling the application removes its registry keys and shortcuts without deleting the user's projects unless explicitly requested.