Desktop App Distribution skill for Codex

Done well means: a user downloads the installer in a browser and opens it on a clean machine with no security warning beyond the normal first-launch prompt, every binary carries a timestamped signature, updates are signed with a key separate from the OS certificate, and a bad release can be halted before it reaches everyone.

Before changing anything

1. Read AGENTS.md, then the packaging config (electron-builder.yml, forge.config.*, tauri.conf.json, Xcode export options, WiX or NSIS scripts) and the release workflow.
2. Inventory signing identities: Apple Developer team and its Developer ID Application (and Installer, for pkg) certificates; Windows code signing provider and where the key lives; update signing keys (Sparkle EdDSA, Tauri minisign, electron-builder feeds).
3. Inventory the current release path: where artifacts are hosted, how the update feed is generated, how many users are on each version.
4. Releasing reaches every installed user, and certificate actions (revoking, re-issuing) can break existing installs. Confirm each publish, feed update and certificate change with the user explicitly.
5. Notarization, timestamp servers and cloud signing need network; signing steps usually run in CI, not in a sandboxed local session.

macOS: sign, notarize, staple

Order matters: sign nested code inside-out, then the app, then the container, then notarize the container and staple.

# 1. Sign (Xcode export with method developer-id does this; manual form for other toolchains)
codesign --force --options runtime --timestamp \
  --entitlements build/entitlements.plist \
  --sign "Developer ID Application: Example Ltd (ABCDE12345)" "build/Example.app"

# 2. Package
hdiutil create -volname Example -srcfolder build/Example.app -ov -format UDZO build/Example.dmg
codesign --timestamp --sign "Developer ID Application: Example Ltd (ABCDE12345)" build/Example.dmg

# 3. Notarize with an App Store Connect API key, then staple
xcrun notarytool submit build/Example.dmg --key "$ASC_KEY_PATH" --key-id "$ASC_KEY_ID" --issuer "$ASC_ISSUER_ID" --wait
xcrun stapler staple build/Example.dmg

# 4. Check as Gatekeeper would
xcrun stapler validate build/Example.dmg
spctl -a -vvv -t open --context context:primary-signature build/Example.dmg
codesign --verify --deep --strict --verbose=2 build/Example.app

• --options runtime (hardened runtime) and --timestamp are required for notarization.
• Do not sign with --deep; it applies one set of entitlements to everything. Sign each helper, framework and login item individually (Electron and Tauri tooling does this).
• On rejection, read xcrun notarytool log <id> ...; the usual causes are an unsigned nested binary, a missing timestamp or a missing hardened runtime.
• A .pkg needs the Developer ID Installer certificate: productbuild --sign "Developer ID Installer: ...".

Windows: Authenticode

Since mid-2023, publicly trusted code signing keys must live in hardware (HSM, token or cloud HSM); .pfx files on build agents are no longer issued.

Option	Fits
Microsoft’s managed service (Azure Trusted Signing, being renamed Artifact Signing)	Organizations eligible for it; integrates with signtool via a dlib
CA cloud signing (DigiCert KeyLocker, SSL.com eSigner, others) or Azure Key Vault + AzureSignTool	Existing OV/EV certificate
Hardware token on a dedicated machine	Small teams with low release volume; poor for CI
Microsoft Store (MSIX submitted to the Store)	Store signs the package; no certificate needed for Store delivery

signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /sha1 <cert-thumbprint> build\ExampleSetup.exe
signtool verify /pa /v build\ExampleSetup.exe

• Sign every executable and DLL you ship, and the installer itself.
• SmartScreen warnings fade as a certificate builds reputation through clean downloads; EV certificates no longer skip that process. Keep the same certificate subject across renewals and warn the user that a brand-new certificate shows warnings at first.
• Always timestamp; without it, signatures become invalid when the certificate expires.

Installer formats

Platform	Default	When else
macOS	Signed, notarized DMG with the app	.pkg when installing system components, launch daemons or for MDM deployment
Windows	NSIS (per-user, no admin) or Squirrel via your framework	MSI for enterprise GPO/Intune; MSIX for Store and clean install/uninstall
Linux	AppImage for direct download + deb/rpm	Flatpak on Flathub for desktop users; Snap if Ubuntu-centric

Also publish to WinGet (manifest PR to microsoft/winget-pkgs) and Homebrew (cask) when the audience is developers; both pick up updates from your release URLs.

Update feeds and channels

Stack	Mechanism	Signing
Native macOS	Sparkle 2 appcast	EdDSA (generate_keys, sign_update) plus Developer ID
Electron	electron-updater (builder) or Squirrel / update.electronjs.org (Forge)	OS code signing; builder also checks publisher on Windows
Tauri	tauri-plugin-updater with latest.json	Tauri signer key plus OS signing
Linux packages	Signed apt/yum repository, Flathub	GPG repo key

• Run at least two channels: beta (opt-in, staff and volunteers) and stable.
• Use staged rollout where the mechanism supports it (Sparkle phased rollout, electron-updater stagingPercentage, or serving the new feed to a percentage of clients from your own endpoint). Watch crash and error rates before widening.
• Rollback: clients rarely downgrade automatically. Halt by reverting the feed to the previous version, then ship a fixed N+1 with a higher version number.
• Update signing keys are as critical as certificates: lose one and existing installs can never update. Keep them in a secret manager with an offline backup and named owners.
• Keep the update feed and artifacts on HTTPS with immutable versioned URLs.

Release workflow

• Version bumped consistently (app, installer metadata, feed)
• Build each OS on its own runner; collect artifacts
• Sign macOS app, package, notarize, staple; sign Windows binaries and installer
• Verify signatures (commands above) in CI; fail the job on any error
• Smoke test installers on clean VMs (no developer certificates installed)
• Ask the user to confirm, then publish artifacts and the beta feed
• After the beta soak period and a second confirmation, publish to stable with staged rollout
• Record checksums (SHA-256) on the release page

Gotchas

• Downloading from a browser adds the quarantine attribute; testing an app copied over scp or built locally skips Gatekeeper entirely and proves nothing.
• Apple Developer ID certificates last five years; set calendar reminders well before expiry and before the Apple Developer membership renewal date.
• Changing the macOS bundle identifier or Windows AppUserModelID breaks updates, notifications and stored settings.
• Antivirus false positives hit unsigned or newly signed NSIS installers; submit samples to the major vendors before a large launch.
• Universal macOS builds need every native dependency for both arm64 and x86_64; check with lipo -archs.

Output

**Release:** <version> channels: beta -> stable (rollout %)
**macOS:** signed (identity), notarization id + status, stapled
**Windows:** signing provider, signtool verify result
**Linux:** formats, repo or store
**Feed:** <URL, signature key owner, previous version kept for rollback>
**Smoke tests:** <OS, clean VM, result>