Orqestria Download
← Back to Go desktop foundation team

Skill · Version 1.0.0

Desktop signing and distribution

Prepares platform-appropriate signatures and installers while making actual distribution checks explicit.

desktop-signing-distribution

Team members using this skill

See how it helps

When is it useful?

Use when shipping desktop installers outside the development machine.

What does it help you do?

  • Checks nested signing order, required entitlements and notarization evidence.
  • Validates Windows signatures and timestamps with installation-scope requirements.
  • Reviews uninstall behavior and ownership of registered file associations.

Try asking this

Prepare a signed macOS installer and report separately signing, notarization and clean-machine launch evidence. Install on a clean test machine and exercise a permission-requiring feature. Record actual operating-system checks separately from successful artifact creation.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

  • SKILL.md