{"title":"Notarizing And Stapling A Mac App For Direct Download","html_url":"https://deallocatedobjects.com/posts/notarizing-and-stapling-a-mac-app-for-direct-download","source_url":"","markdown_content":"Every Mac app I sell from my own site goes out the same way. It's signed with Developer ID, notarized, stapled, put in a DMG, and then the DMG gets signed, notarized and stapled too. The steps are well known. The order is where people get bitten, along with which file each step applies to.\n\nHere's the sequence my release scripts run, with the flags and the reason behind each one.\n\n### Signing With Hardened Runtime And A Timestamp\n\nBefore the notary service accepts an upload, every executable in it has to be signed with Developer ID, have the hardened runtime turned on and carry a secure timestamp. The debug-only `com.apple.security.get-task-allow` entitlement gets it rejected.\n\nIf Xcode does the signing, `ENABLE_HARDENED_RUNTIME: YES` in the target's settings turns on the hardened runtime, and exporting the archive with the `developer-id` method handles the Developer ID signature and the timestamp:\n\n```xml title=\"ExportOptions.plist\"\nmethod\ndeveloper-id\nteamID\nTEAMID\n```\n\n```bash\nxcodebuild -exportArchive -archivePath build/MyApp.xcarchive \\\n -exportOptionsPlist build/ExportOptions.plist -exportPath build/export\n```\n\nThe export re-signs every nested framework, XPC service and helper app with your Developer ID certificate, the runtime flag and a timestamp. After it finishes, my scripts make sure the debug entitlement didn't slip through, because it's quicker to catch that before uploading than to read about it in a notary log:\n\n```bash\nif codesign -d --entitlements - \"$app\" 2>/dev/null | grep -q \"get-task-allow\"; then\n echo \"ERROR: exported app carries com.apple.security.get-task-allow\" >&2; exit 1\nfi\n```\n\n### Inside Out, Without --deep\n\nSometimes the signing has to happen outside Xcode, for instance when the build needs provisioning profiles and entitlements generated at release time. Then you sign each piece yourself, starting from the deepest code and working outward.\n\nOrder matters because a bundle's signature records the signatures of the code nested inside it. Sign the app first and a framework second, and the app's seal no longer matches what's on disk.\n\nThe tempting shortcut is `codesign --deep`. `man codesign` marks it \"DEPRECATED for signing as of macOS 13.0\", and the warning right under that is the real reason to skip it: \"All signing options will be applied, in turn, to all nested content. This is almost never what you want.\" Pass `--entitlements` along with `--deep` and your app's entitlements end up on Sparkle's XPC services too. Sparkle's docs warn against `--deep` for exactly this reason: its downloader service is signed with entitlements of its own. It also only finds nested code in a fixed list of locations (`Contents/Frameworks`, `Contents/XPCServices`, `Contents/Helpers`, `Contents/Library/LoginItems` and a few more), and anything elsewhere goes unsigned.\n\nHere's the inside-out version for an app that embeds Sparkle 2, in the order Sparkle's own docs give:\n\n```bash title=\"sign.sh\"\nIDENTITY=\"Developer ID Application: Your Name (TEAMID)\"\ncs=(codesign --force --timestamp --options runtime --sign \"$IDENTITY\")\nfw=\"MyApp.app/Contents/Frameworks/Sparkle.framework\"\nfwv=\"$fw/Versions/$(readlink \"$fw/Versions/Current\")\"\n\n\"${cs[@]}\" \"$fwv/XPCServices/Installer.xpc\"\n\"${cs[@]}\" --preserve-metadata=entitlements \"$fwv/XPCServices/Downloader.xpc\"\n\"${cs[@]}\" \"$fwv/Autoupdate\"\n\"${cs[@]}\" \"$fwv/Updater.app\"\n\"${cs[@]}\" \"$fw\"\n\"${cs[@]}\" --entitlements MyApp.entitlements MyApp.app\n```\n\n`--preserve-metadata=entitlements` keeps the entitlements Sparkle already gave its downloader service, and the app's own entitlements only go on the last line. `--deep` is still the right flag when verifying, which comes up at the end.\n\n### Notarizing With A Stored Profile\n\n`notarytool` reads credentials from the keychain, so the password never goes in a script. Store them once:\n\n```bash\nxcrun notarytool store-credentials notary-profile \\\n --apple-id you@example.com --team-id TEAMID\n```\n\nLeave out `--password` and it prompts for an app-specific password, then checks the credentials with Apple before saving them (`--validate` is the default).\n\n`notarytool submit` takes a file, so the app goes up as a zip. `ditto -c -k --keepParent` makes a PKZip archive with `MyApp.app` as its top-level folder:\n\n```bash title=\"release.sh\"\nnotarize() { # path to a .zip or .dmg\n local out id status\n out=$(xcrun notarytool submit \"$1\" --keychain-profile notary-profile --wait 2>&1)\n status=$(echo \"$out\" | awk '/^ *status:/{s=$2} END{print s}')\n if [ \"$status\" != \"Accepted\" ]; then\n id=$(echo \"$out\" | awk '/^ *id:/{print $2; exit}')\n echo \"ERROR: notarization of $(basename \"$1\") was not accepted.\" >&2\n [ -n \"$id\" ] && xcrun notarytool log \"$id\" --keychain-profile notary-profile >&2\n exit 1\n fi\n}\n\nditto -c -k --keepParent build/export/MyApp.app build/MyApp-notarize.zip\nnotarize build/MyApp-notarize.zip\n```\n\n`--wait` keeps the command running until the service finishes, so the script can move on to stapling. The function reads the `status:` line and stops on anything other than `Accepted`. When a submission fails, `notarytool log` prints the service's JSON report, which names each file that failed and why, for example a nested binary with no secure timestamp.\n\n### Staple The App Before It Goes In The DMG\n\nNotarization creates a ticket on Apple's side. Without a stapled ticket, Gatekeeper has to look it up online the first time someone opens your app. Stapling attaches the ticket to the file so the check works with no network.\n\nEach stapled file only carries its own ticket. The DMG's ticket stays with the DMG. When someone drags the app to Applications, the copy is still quarantined, Gatekeeper checks it again at first launch, and it needs a ticket of its own. So the app gets stapled first, while it's still a plain folder on disk:\n\n```bash\nxcrun stapler staple build/export/MyApp.app\nxcrun stapler validate build/export/MyApp.app\n```\n\nThe zip you uploaded is only a container for the upload. `stapler` lists the formats it supports as \"UDIF disk images, code-signed executable bundles, and signed 'flat' installer packages\", so the ticket goes on the `.app` and the zip gets thrown away. In a bundle the ticket lands in `Contents/CodeResources`, which is why stapling has to happen before the app goes into a compressed, read-only DMG.\n\n### Then The DMG Gets The Same Treatment\n\nThe DMG is the first thing Gatekeeper checks after a download, so it needs its own signature, notarization and ticket. A disk image isn't executable code, so my scripts sign it with `--timestamp` and no runtime flag:\n\n```bash\nmkdir build/dmg-src && ditto build/export/MyApp.app build/dmg-src/MyApp.app\ncreate-dmg --volname MyApp --app-drop-link 450 190 build/MyApp.dmg build/dmg-src\ncodesign --force --timestamp --sign \"$IDENTITY\" build/MyApp.dmg\nnotarize build/MyApp.dmg\nxcrun stapler staple build/MyApp.dmg\n```\n\nStapling writes into the DMG, so anything that hashes or signs the final file has to come after it. My scripts generate Sparkle's EdDSA signature for the appcast right after stapling, from the finished DMG.\n\n### Checking What People Download\n\nMy release scripts end with checks that ask the same questions Gatekeeper will. For the app:\n\n```bash\nspctl -a -vvv -t exec MyApp.app\nxcrun stapler validate MyApp.app\ncodesign --verify --deep --strict --verbose=2 MyApp.app\ncodesign -dvv MyApp.app 2>&1 | grep -E \"flags|Timestamp|Notarization\"\n```\n\nA good result says `accepted` with `source=Notarized Developer ID`, then \"The validate action worked!\", then `valid on disk` and `satisfies its Designated Requirement`. Here `--deep` checks every nested piece in full, where the default is only a shallow pass. The last line should show `flags=0x10000(runtime)`, a `Timestamp=` line and `Notarization Ticket=stapled`.\n\nThe DMG needs a different assessment type. The default `execute` type rejects it with \"the code is valid but does not seem to be an app\". `-t open` on its own comes back `rejected` with `source=Insufficient Context`. `--context` isn't in `man spctl`, but this is the form that comes back `accepted`:\n\n```bash\nspctl -a -vvv -t open --context context:primary-signature MyApp.dmg\nxcrun stapler validate MyApp.dmg\n```\n\nOn my Mac, `-t install` also accepts a signed DMG, though `man spctl` describes that type as the one for installer packages, so my scripts stick to `-t open`. An unsigned DMG fails both with `source=no usable signature`.\n\nLast, check the app as the buyer gets it, from inside the mounted DMG:\n\n```bash\nhdiutil attach -nobrowse -quiet build/MyApp.dmg\nxcrun stapler validate /Volumes/MyApp/MyApp.app\nspctl -a -vvv /Volumes/MyApp/MyApp.app\nhdiutil detach /Volumes/MyApp -quiet\n```\n\nIf the app was stapled before packaging, `stapler validate` passes here too. If it fails, the app in the DMG has no ticket of its own, and Gatekeeper can't confirm it was notarized when someone opens it for the first time without a network connection.","html_content":"

Every Mac app I sell from my own site goes out the same way. It’s signed with Developer ID, notarized, stapled, put in a DMG, and then the DMG gets signed, notarized and stapled too. The steps are well known. The order is where people get bitten, along with which file each step applies to.

\n

Here’s the sequence my release scripts run, with the flags and the reason behind each one.

\n

Signing With Hardened Runtime And A Timestamp

\n

Before the notary service accepts an upload, every executable in it has to be signed with Developer ID, have the hardened runtime turned on and carry a secure timestamp. The debug-only com.apple.security.get-task-allow entitlement gets it rejected.

\n

If Xcode does the signing, ENABLE_HARDENED_RUNTIME: YES in the target’s settings turns on the hardened runtime, and exporting the archive with the developer-id method handles the Developer ID signature and the timestamp:

\n
ExportOptions.plistXML
<key>method</key>\n<string>developer-id</string>\n<key>teamID</key>\n<string>TEAMID</string>
Shell
xcodebuild -exportArchive -archivePath build/MyApp.xcarchive \\\n  -exportOptionsPlist build/ExportOptions.plist -exportPath build/export

The export re-signs every nested framework, XPC service and helper app with your Developer ID certificate, the runtime flag and a timestamp. After it finishes, my scripts make sure the debug entitlement didn’t slip through, because it’s quicker to catch that before uploading than to read about it in a notary log:

\n
Shell
if codesign -d --entitlements - \"$app\" 2>/dev/null | grep -q \"get-task-allow\"; then\n  echo \"ERROR: exported app carries com.apple.security.get-task-allow\" >&2; exit 1\nfi

Inside Out, Without --deep

\n

Sometimes the signing has to happen outside Xcode, for instance when the build needs provisioning profiles and entitlements generated at release time. Then you sign each piece yourself, starting from the deepest code and working outward.

\n

Order matters because a bundle’s signature records the signatures of the code nested inside it. Sign the app first and a framework second, and the app’s seal no longer matches what’s on disk.

\n

The tempting shortcut is codesign --deep. man codesign marks it “DEPRECATED for signing as of macOS 13.0”, and the warning right under that is the real reason to skip it: “All signing options will be applied, in turn, to all nested content. This is almost never what you want.” Pass --entitlements along with --deep and your app’s entitlements end up on Sparkle’s XPC services too. Sparkle’s docs warn against --deep for exactly this reason: its downloader service is signed with entitlements of its own. It also only finds nested code in a fixed list of locations (Contents/Frameworks, Contents/XPCServices, Contents/Helpers, Contents/Library/LoginItems and a few more), and anything elsewhere goes unsigned.

\n

Here’s the inside-out version for an app that embeds Sparkle 2, in the order Sparkle’s own docs give:

\n
sign.shShell
IDENTITY=\"Developer ID Application: Your Name (TEAMID)\"\ncs=(codesign --force --timestamp --options runtime --sign \"$IDENTITY\")\nfw=\"MyApp.app/Contents/Frameworks/Sparkle.framework\"\nfwv=\"$fw/Versions/$(readlink \"$fw/Versions/Current\")\"\n\n\"${cs[@]}\" \"$fwv/XPCServices/Installer.xpc\"\n\"${cs[@]}\" --preserve-metadata=entitlements \"$fwv/XPCServices/Downloader.xpc\"\n\"${cs[@]}\" \"$fwv/Autoupdate\"\n\"${cs[@]}\" \"$fwv/Updater.app\"\n\"${cs[@]}\" \"$fw\"\n\"${cs[@]}\" --entitlements MyApp.entitlements MyApp.app

--preserve-metadata=entitlements keeps the entitlements Sparkle already gave its downloader service, and the app’s own entitlements only go on the last line. --deep is still the right flag when verifying, which comes up at the end.

\n

Notarizing With A Stored Profile

\n

notarytool reads credentials from the keychain, so the password never goes in a script. Store them once:

\n
Shell
xcrun notarytool store-credentials notary-profile \\\n  --apple-id you@example.com --team-id TEAMID

Leave out --password and it prompts for an app-specific password, then checks the credentials with Apple before saving them (--validate is the default).

\n

notarytool submit takes a file, so the app goes up as a zip. ditto -c -k --keepParent makes a PKZip archive with MyApp.app as its top-level folder:

\n
release.shShell
notarize() { # path to a .zip or .dmg\n  local out id status\n  out=$(xcrun notarytool submit \"$1\" --keychain-profile notary-profile --wait 2>&1)\n  status=$(echo \"$out\" | awk '/^ *status:/{s=$2} END{print s}')\n  if [ \"$status\" != \"Accepted\" ]; then\n    id=$(echo \"$out\" | awk '/^ *id:/{print $2; exit}')\n    echo \"ERROR: notarization of $(basename \"$1\") was not accepted.\" >&2\n    [ -n \"$id\" ] && xcrun notarytool log \"$id\" --keychain-profile notary-profile >&2\n    exit 1\n  fi\n}\n\nditto -c -k --keepParent build/export/MyApp.app build/MyApp-notarize.zip\nnotarize build/MyApp-notarize.zip

--wait keeps the command running until the service finishes, so the script can move on to stapling. The function reads the status: line and stops on anything other than Accepted. When a submission fails, notarytool log prints the service’s JSON report, which names each file that failed and why, for example a nested binary with no secure timestamp.

\n

Staple The App Before It Goes In The DMG

\n

Notarization creates a ticket on Apple’s side. Without a stapled ticket, Gatekeeper has to look it up online the first time someone opens your app. Stapling attaches the ticket to the file so the check works with no network.

\n

Each stapled file only carries its own ticket. The DMG’s ticket stays with the DMG. When someone drags the app to Applications, the copy is still quarantined, Gatekeeper checks it again at first launch, and it needs a ticket of its own. So the app gets stapled first, while it’s still a plain folder on disk:

\n
Shell
xcrun stapler staple build/export/MyApp.app\nxcrun stapler validate build/export/MyApp.app

The zip you uploaded is only a container for the upload. stapler lists the formats it supports as “UDIF disk images, code-signed executable bundles, and signed ‘flat’ installer packages”, so the ticket goes on the .app and the zip gets thrown away. In a bundle the ticket lands in Contents/CodeResources, which is why stapling has to happen before the app goes into a compressed, read-only DMG.

\n

Then The DMG Gets The Same Treatment

\n

The DMG is the first thing Gatekeeper checks after a download, so it needs its own signature, notarization and ticket. A disk image isn’t executable code, so my scripts sign it with --timestamp and no runtime flag:

\n
Shell
mkdir build/dmg-src && ditto build/export/MyApp.app build/dmg-src/MyApp.app\ncreate-dmg --volname MyApp --app-drop-link 450 190 build/MyApp.dmg build/dmg-src\ncodesign --force --timestamp --sign \"$IDENTITY\" build/MyApp.dmg\nnotarize build/MyApp.dmg\nxcrun stapler staple build/MyApp.dmg

Stapling writes into the DMG, so anything that hashes or signs the final file has to come after it. My scripts generate Sparkle’s EdDSA signature for the appcast right after stapling, from the finished DMG.

\n

Checking What People Download

\n

My release scripts end with checks that ask the same questions Gatekeeper will. For the app:

\n
Shell
spctl -a -vvv -t exec MyApp.app\nxcrun stapler validate MyApp.app\ncodesign --verify --deep --strict --verbose=2 MyApp.app\ncodesign -dvv MyApp.app 2>&1 | grep -E \"flags|Timestamp|Notarization\"

A good result says accepted with source=Notarized Developer ID, then “The validate action worked!”, then valid on disk and satisfies its Designated Requirement. Here --deep checks every nested piece in full, where the default is only a shallow pass. The last line should show flags=0x10000(runtime), a Timestamp= line and Notarization Ticket=stapled.

\n

The DMG needs a different assessment type. The default execute type rejects it with “the code is valid but does not seem to be an app”. -t open on its own comes back rejected with source=Insufficient Context. --context isn’t in man spctl, but this is the form that comes back accepted:

\n
Shell
spctl -a -vvv -t open --context context:primary-signature MyApp.dmg\nxcrun stapler validate MyApp.dmg

On my Mac, -t install also accepts a signed DMG, though man spctl describes that type as the one for installer packages, so my scripts stick to -t open. An unsigned DMG fails both with source=no usable signature.

\n

Last, check the app as the buyer gets it, from inside the mounted DMG:

\n
Shell
hdiutil attach -nobrowse -quiet build/MyApp.dmg\nxcrun stapler validate /Volumes/MyApp/MyApp.app\nspctl -a -vvv /Volumes/MyApp/MyApp.app\nhdiutil detach /Volumes/MyApp -quiet

If the app was stapled before packaging, stapler validate passes here too. If it fails, the app in the DMG has no ticket of its own, and Gatekeeper can’t confirm it was notarized when someone opens it for the first time without a network connection.

","created_at":"2026-11-05T14:00:00.000Z","updated_at":"2026-11-05T14:00:00.000Z"}