SPB Git

Repository Public

notarization.md 9.1 KB

# 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: Notarization sequence of Scripts/notarize.sh

The four numbered stages printed by the script:

  1. Submitting the application. The app is zipped with ditto -c -k --keepParent into build/notary/ORIXSheet-app.zip (a ZIP is only the transport container; the ticket is issued for the code inside). submit runs xcrun notarytool submit <file> --keychain-profile <profile> --wait --output-format json.
  2. Stapling the application. xcrun stapler staple then xcrun stapler validate on dist/ORIX Sheet.app.
  3. Packaging. Scripts/package.sh builds dist/ORIXSheet-<version>.dmg and dist/ORIXSheet-<version>.zip from the now-stapled app and signs the DMG (see distribution).
  4. Submitting and stapling the disk image. Same submit function on the DMG, then stapler staple and stapler validate on 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 submit itself fails (credentials, network, service refusal), the first 8 lines of its error output are shown and the function fails;
  • otherwise the status and id fields are read from the JSON answer and printed as Submission <id>: <status>;
  • the notary log of that submission is fetched with notarytool log into build/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:

bash
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

  1. Read the log. build/notary/app-log.json (or dmg-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.

  2. Map the issue to the signing step. The checks of Scripts/sign.sh correspond to the usual causes:

    Notary issue Check in this project
    binary not signed with a valid Developer ID certificate the per-file TeamIdentifier loop of sign.sh; look for a Mach-O outside the patterns the script signs (*.dylib, Helpers/, Resources/, *.framework, *.bundle)
    signature without a secure timestamp every codesign call of sign.sh passes --timestamp; the build machine needs network access to Apple's timestamp server
    hardened runtime not enabled the per-file flags=…runtime loop
    get-task-allow entitlement present explicit check in sign.sh; CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO in project.yml
    a nested library signed by another team the DuckDB case, see signing

    Source: Scripts/sign.sh.

  3. Fix, rebuild, re-sign. Never patch a signed bundle: run Scripts/sign.sh again (it rebuilds and re-signs from scratch), then Scripts/notarize.sh.

  4. If the app was accepted and only the DMG failed (exit 3): the app in dist/ is already stapled. Re-running notarize.sh submits the app again before rebuilding the DMG; that is harmless but slow. The alternative is to run Scripts/package.sh and submit the DMG by hand with the same notarytool submit … --wait command.

  5. If notarytool submit itself 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.
Files main
Menu

Theme