Notarization
Notarization is implemented by Scripts/notarize.sh (44 lines). It submits the signed application
to Apple's notary service with notarytool, staples the ticket, builds the disk image and ZIP,
notarizes and staples the disk image, writes checksums and runs Gatekeeper assessments.
Before: signing. After: distribution. Gates: release checklist.
This document describes the mechanism only. The result of a notarization run for ORIX Sheet
(submission status, stapling, checksums, Gatekeeper assessments) is recorded in RELEASE-REPORT.md
at the repository root: see RELEASE-REPORT.md. The bundle that is submitted contains three Mach-O
files — the app executable, the embedded orix-sheet tool and libduckdb.dylib — all signed by
Scripts/sign.sh with the hardened runtime and a secure timestamp (signing).
Prerequisites
| Requirement | Detail |
|---|---|
| A signed app | dist/ORIX Sheet.app produced by Scripts/sign.sh; the script exits 1 if it is missing |
| Credentials | an existing notarytool keychain profile, name taken from NOTARY_PROFILE, default MacLustr-Notarize |
| Tools | xcrun notarytool, xcrun stapler, ditto, shasum, spctl, /usr/bin/python3 (used only to read the JSON answer) |
| Network | access to Apple's notary service; this is the only release step that uploads anything |
Source: Scripts/notarize.sh.
The script "never creates, prints or changes credentials" (its header). The profile is created
once, outside the repository, with xcrun notarytool store-credentials; the password or API key is
held by the keychain. docs/research/technology-evaluation.md records that the profile
MacLustr-Notarize existed on the build machine during the environment audit. Do not put the
store-credentials command with a password in a file: Scripts/secret-scan.sh has a pattern for
exactly that.
Workflow
sequenceDiagram
participant S as notarize.sh
participant N as Apple notary service
participant P as package.sh
S->>S: ditto zip of the signed app
S->>N: notarytool submit app zip, wait
N-->>S: status and submission id
S->>N: notarytool log id
N-->>S: JSON log saved in build/notary
Note over S,N: continue only if status is Accepted
S->>S: stapler staple and validate the app
S->>P: build DMG and ZIP from the stapled app
P-->>S: dist/ORIXSheet-version.dmg and .zip
S->>N: notarytool submit DMG, wait
N-->>S: status and submission id
S->>S: stapler staple and validate the DMG
S->>S: shasum, spctl assessments
SVG fallback:
The four numbered stages printed by the script:
- Submitting the application. The app is zipped with
ditto -c -k --keepParentintobuild/notary/ORIXSheet-app.zip(a ZIP is only the transport container; the ticket is issued for the code inside).submitrunsxcrun notarytool submit <file> --keychain-profile <profile> --wait --output-format json. - Stapling the application.
xcrun stapler staplethenxcrun stapler validateondist/ORIX Sheet.app. - Packaging.
Scripts/package.shbuildsdist/ORIXSheet-<version>.dmganddist/ORIXSheet-<version>.zipfrom the now-stapled app and signs the DMG (see distribution). - Submitting and stapling the disk image. Same
submitfunction on the DMG, thenstapler stapleandstapler validateon it.
Then: SHA-256 checksums of the DMG and ZIP are written to dist/ORIXSheet-<version>.sha256, and two
Gatekeeper assessments are printed.
The ZIP in dist/ is not submitted on its own: a ZIP cannot carry a stapled ticket. It contains
the stapled application.
The submit function
submit <file> <name> succeeds only when Apple's answer is Accepted:
- if
notarytool submititself fails (credentials, network, service refusal), the first 8 lines of its error output are shown and the function fails; - otherwise the
statusandidfields are read from the JSON answer and printed asSubmission <id>: <status>; - the notary log of that submission is fetched with
notarytool logintobuild/notary/<name>-log.json(a failure to fetch the log is ignored); - the function's result is the test
status == "Accepted".
The header of the script states the rule this implements: the word "notarized" is printed only when Apple's service answered Accepted.
Files written
| File | Content |
|---|---|
build/notary/ORIXSheet-app.zip |
the archive uploaded for the app |
build/notary/app.json, build/notary/dmg.json |
JSON answer of each submission (id, status) |
build/notary/app.json.err, build/notary/dmg.json.err |
standard error of notarytool submit |
build/notary/app-log.json, build/notary/dmg-log.json |
the notary log of each submission |
dist/ORIXSheet-<version>.dmg, .zip, .sha256 |
distribution artifacts |
Source: Scripts/notarize.sh. build/ and dist/ are ignored by git (.gitignore).
Exit status and final messages
| Exit | Meaning | Message |
|---|---|---|
| 0 | app and DMG accepted and stapled | RESULT: … are notarized by Apple and stapled. |
| 1 | dist/ORIX Sheet.app missing |
ERROR: … not found. Run Scripts/sign.sh first. |
| other non-zero | because of set -euo pipefail, the status of any failing command not otherwise handled (stapler, package.sh, shasum, spctl) |
no RESULT line |
| 2 | the app submission was not accepted | RESULT: NOT notarized. … is signed but carries no notarization ticket. |
| 3 | the app is notarized and stapled, the DMG submission was not accepted | RESULT: the app is notarized and stapled, the DMG is NOT. |
Source: Scripts/notarize.sh.
Gatekeeper checks
Run by the script at the end, and usable by hand:
spctl --assess --type execute --verbose=2 "dist/ORIX Sheet.app"
spctl --assess --type open --context context:primary-signature --verbose=2 "dist/ORIXSheet-1.0.0.dmg"
xcrun stapler validate "dist/ORIX Sheet.app"
xcrun stapler validate "dist/ORIXSheet-1.0.0.dmg"The script has no explicit test of the spctl answers, but it runs under set -euo pipefail: a
non-zero status from spctl (a rejected assessment) aborts the script with that pipeline's status
before the final RESULT line is printed. Read the two printed lines all the same; for a notarized
Developer ID build the expected source is "Notarized Developer ID".
Not automated and not recorded as done: a first-launch test of the downloaded DMG on a second Mac (quarantine attribute set by a browser), which is the only test of the full Gatekeeper path.
What to do on rejection
-
Read the log.
build/notary/app-log.json(ordmg-log.json) lists every issue with the path of the offending file inside the bundle. If it was not fetched:xcrun notarytool log <submission-id> --keychain-profile "$NOTARY_PROFILE".xcrun notarytool history --keychain-profile "$NOTARY_PROFILE"lists past submissions. -
Map the issue to the signing step. The checks of
Scripts/sign.shcorrespond to the usual causes:Notary issue Check in this project binary not signed with a valid Developer ID certificate the per-file TeamIdentifierloop ofsign.sh; look for a Mach-O outside the patterns the script signs (*.dylib,Helpers/,Resources/,*.framework,*.bundle)signature without a secure timestamp every codesigncall ofsign.shpasses--timestamp; the build machine needs network access to Apple's timestamp serverhardened runtime not enabled the per-file flags=…runtimeloopget-task-allowentitlement presentexplicit check in sign.sh;CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NOinproject.ymla nested library signed by another team the DuckDB case, see signing Source:
Scripts/sign.sh. -
Fix, rebuild, re-sign. Never patch a signed bundle: run
Scripts/sign.shagain (it rebuilds and re-signs from scratch), thenScripts/notarize.sh. -
If the app was accepted and only the DMG failed (exit 3): the app in
dist/is already stapled. Re-runningnotarize.shsubmits the app again before rebuilding the DMG; that is harmless but slow. The alternative is to runScripts/package.shand submit the DMG by hand with the samenotarytool submit … --waitcommand. -
If
notarytool submititself fails: check the profile name (NOTARY_PROFILE), that the profile exists in the keychain of the user running the script, and network access. Agreement updates on the developer account also block submissions; those need the account holder.
Limits
- No timeout is passed to
--wait; the script waits as long as the service takes. - A submission uploads the application to Apple. It is the one release step that sends anything off the machine, and it needs the owner's credentials.
- The script does not record the accepted submission ids anywhere but
build/notary/, which is not in git. Copy them into the release notes if they must be kept.