Repository Public License
1<!-- ORIX Clean / File: docs/release/notarization.md / Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai -->2# Notarization34How `Scripts/notarize.sh` submits the application and the disk image to Apple's notary service, staples the5ticket and reports the result, and how to verify it independently.67This document describes a procedure. It does not state that any build has been notarized. The script itself8prints the word "notarized" only after Apple's service answered `Accepted`.910## Credentials1112- The script uses an **existing** `notarytool` keychain profile. The profile name is taken from the environment13 variable `NOTARY_PROFILE` and defaults to `MacLustr-Notarize`.14- The profile is created once, outside this repository, with `xcrun notarytool store-credentials <name>`. It15 lives in the login keychain of the build machine.16- The script never creates, prints or changes credentials. **No credential is stored in the repository**: no17 Apple ID, app-specific password, API key or key file. `Scripts/check.sh` fails on `AuthKey_*`, `.p8` and18 similar files and on credential-like strings.1920```sh21NOTARY_PROFILE=MyProfile Scripts/notarize.sh # another profile22Scripts/notarize.sh # default profile, default target23```2425## Usage2627```28Scripts/notarize.sh [target] [name]29```3031| Argument | Default | Meaning |32|---|---|---|33| `target` | `dist/ORIX Clean.app` | What to notarize: the application bundle or the disk image |34| `name` | `app` | Label for the files written to `build/notary/` |3536The release needs two submissions:3738```sh39Scripts/notarize.sh # the application40Scripts/package.sh # builds the DMG and the ZIP from the stapled app41Scripts/notarize.sh dist/ORIXClean-<version>.dmg dmg # the disk image42```4344The application is notarized first because `package.sh` refuses to run until the application is stapled, so45that the copy inside the disk image and the ZIP already carries its ticket.4647## What the script does4849```mermaid50sequenceDiagram51 participant S as notarize.sh52 participant N as Apple notary service53 participant T as stapler54 S->>S: check that the target exists55 S->>S: if the target is a bundle, zip it with ditto into build/notary56 S->>N: notarytool submit with keychain profile, wait, JSON output57 N-->>S: submission id and status58 S->>N: notarytool log for the submission id59 N-->>S: log saved as JSON60 alt status is Accepted61 S->>T: stapler staple the target62 S->>T: stapler validate the target63 S->>S: print RESULT notarized and stapled64 else any other status65 S->>S: print RESULT NOT notarized, exit 366 end67```68691. Stops with exit code 1 if the target does not exist.702. A bundle cannot be uploaded as a directory: it is archived to `build/notary/<name>.zip` with71 `ditto -c -k --keepParent`. A disk image is submitted as is.723. Runs `xcrun notarytool submit … --keychain-profile "$PROFILE" --wait --output-format json`. The JSON answer73 goes to `build/notary/<name>.json`, standard error to `build/notary/<name>.json.err`. If the command itself74 fails (network, credentials, malformed upload), the first lines of the error are shown and the script exits75 with code 2.764. Reads `status` and `id` from the JSON and prints `submission <id>: <status>`.775. Downloads the notary log to `build/notary/<name>-log.json` (best effort).786. If the status is not exactly `Accepted`, prints `RESULT: NOT notarized` with the log path and exits with79 code 3.807. Staples the ticket to the original target (the bundle, not the temporary zip) with `xcrun stapler staple`,81 then runs `xcrun stapler validate`.828. Prints `RESULT: <target> is notarized by Apple (submission <id>) and stapled.`8384| Exit code | Meaning |85|---|---|86| 0 | Accepted, stapled and validated |87| 1 | Target not found |88| 2 | `notarytool submit` failed before a verdict |89| 3 | A verdict other than `Accepted` |90| other | `stapler` failed (the script runs with `set -e`) |9192## Files written9394| File | Content |95|---|---|96| `build/notary/app.zip` | Upload archive of the application |97| `build/notary/app.json`, `dmg.json` | Answer of `notarytool submit`: `id`, `status`, `message` |98| `build/notary/app.json.err`, `dmg.json.err` | Standard error of the submission |99| `build/notary/app-log.json`, `dmg-log.json` | Notary log: issues found, per file |100101`build/` is ignored by git. `Scripts/finalize.sh` later reads the submission ids from `app.json` and102`dmg.json`.103104## Verifying independently105106Do not rely on the script's last line alone; check the artifacts.107108| Check | Command | Expected |109|---|---|---|110| Ticket is attached to the app | `xcrun stapler validate "dist/ORIX Clean.app"` | `The validate action worked!` |111| Ticket is attached to the image | `xcrun stapler validate dist/ORIXClean-<version>.dmg` | `The validate action worked!` |112| Gatekeeper accepts the app | `spctl --assess --type execute --verbose=2 "dist/ORIX Clean.app"` | `accepted`, `source=Notarized Developer ID` |113| Gatekeeper accepts the image | `spctl --assess --type open --context context:primary-signature --verbose=2 dist/ORIXClean-<version>.dmg` | `accepted`, `source=Notarized Developer ID` |114| Service-side record | `xcrun notarytool info <submission id> --keychain-profile "$NOTARY_PROFILE"` | `status: Accepted` |115| Service-side history | `xcrun notarytool history --keychain-profile "$NOTARY_PROFILE"` | The submission is listed |116117The exact wording of `spctl` and `stapler` output can vary between macOS versions; the verdict (`accepted`,118validation succeeded) is what matters. The strongest end-to-end check is on a second Mac that has never seen119the build: download the image, open it, drag the application to Applications and launch it. Gatekeeper should120show the standard first-launch dialog for an application downloaded from the internet, with no warning about121an unidentified developer.122123## When the verdict is not Accepted124125Open `build/notary/<name>-log.json`. Typical findings and their source in this project:126127| Finding in the log | Usual cause |128|---|---|129| The signature does not include a secure timestamp | `--timestamp` missing from `OTHER_CODE_SIGN_FLAGS` |130| The executable does not have the hardened runtime enabled | `ENABLE_HARDENED_RUNTIME` off |131| The executable requests the `get-task-allow` entitlement | A Debug build, or base entitlements injected |132| The binary is not signed with a valid Developer ID certificate | Ad hoc or development identity used |133134`Scripts/sign.sh` checks the last three before any upload. Fix the cause, run `Scripts/sign.sh` again and135resubmit; a rejected submission cannot be amended.136137## Notes138139- Notarization requires network access from the build machine. The application itself contains no network140 code; this is a property of the release tooling only.141- Stapling lets Gatekeeper verify the ticket offline. An unstapled but notarized application still passes when142 the Mac is online, but the release process requires stapling.143- The ZIP artifact is not submitted separately: it is created from the already stapled application bundle.144