Repository Public
1# Notarization23Notarization is implemented by `Scripts/notarize.sh` (44 lines). It submits the signed application4to Apple's notary service with `notarytool`, staples the ticket, builds the disk image and ZIP,5notarizes and staples the disk image, writes checksums and runs Gatekeeper assessments.67Before: [signing](signing.md). After: [distribution](distribution.md). Gates:8[release checklist](checklist.md).910This document describes the mechanism only. The result of a notarization run for ORIX Sheet11(submission status, stapling, checksums, Gatekeeper assessments) is recorded in `RELEASE-REPORT.md`12at the repository root: see `RELEASE-REPORT.md`. The bundle that is submitted contains three Mach-O13files — the app executable, the embedded `orix-sheet` tool and `libduckdb.dylib` — all signed by14`Scripts/sign.sh` with the hardened runtime and a secure timestamp ([signing](signing.md)).1516## Prerequisites1718| Requirement | Detail |19|---|---|20| A signed app | `dist/ORIX Sheet.app` produced by `Scripts/sign.sh`; the script exits 1 if it is missing |21| Credentials | an **existing** `notarytool` keychain profile, name taken from `NOTARY_PROFILE`, default `MacLustr-Notarize` |22| Tools | `xcrun notarytool`, `xcrun stapler`, `ditto`, `shasum`, `spctl`, `/usr/bin/python3` (used only to read the JSON answer) |23| Network | access to Apple's notary service; this is the only release step that uploads anything |2425Source: `Scripts/notarize.sh`.2627The script "never creates, prints or changes credentials" (its header). The profile is created28once, outside the repository, with `xcrun notarytool store-credentials`; the password or API key is29held by the keychain. `docs/research/technology-evaluation.md` records that the profile30`MacLustr-Notarize` existed on the build machine during the environment audit. Do not put the31`store-credentials` command with a password in a file: `Scripts/secret-scan.sh` has a pattern for32exactly that.3334## Workflow3536<!-- diagram: notarization-sequence -->37```mermaid38sequenceDiagram39 participant S as notarize.sh40 participant N as Apple notary service41 participant P as package.sh42 S->>S: ditto zip of the signed app43 S->>N: notarytool submit app zip, wait44 N-->>S: status and submission id45 S->>N: notarytool log id46 N-->>S: JSON log saved in build/notary47 Note over S,N: continue only if status is Accepted48 S->>S: stapler staple and validate the app49 S->>P: build DMG and ZIP from the stapled app50 P-->>S: dist/ORIXSheet-version.dmg and .zip51 S->>N: notarytool submit DMG, wait52 N-->>S: status and submission id53 S->>S: stapler staple and validate the DMG54 S->>S: shasum, spctl assessments55```5657SVG fallback: 5859The four numbered stages printed by the script:60611. **Submitting the application.** The app is zipped with `ditto -c -k --keepParent` into62 `build/notary/ORIXSheet-app.zip` (a ZIP is only the transport container; the ticket is issued63 for the code inside). `submit` runs64 `xcrun notarytool submit <file> --keychain-profile <profile> --wait --output-format json`.652. **Stapling the application.** `xcrun stapler staple` then `xcrun stapler validate` on66 `dist/ORIX Sheet.app`.673. **Packaging.** `Scripts/package.sh` builds `dist/ORIXSheet-<version>.dmg` and68 `dist/ORIXSheet-<version>.zip` from the now-stapled app and signs the DMG69 (see [distribution](distribution.md)).704. **Submitting and stapling the disk image.** Same `submit` function on the DMG, then71 `stapler staple` and `stapler validate` on it.7273Then: SHA-256 checksums of the DMG and ZIP are written to `dist/ORIXSheet-<version>.sha256`, and two74Gatekeeper assessments are printed.7576The ZIP in `dist/` is not submitted on its own: a ZIP cannot carry a stapled ticket. It contains77the stapled application.7879### The `submit` function8081`submit <file> <name>` succeeds only when Apple's answer is `Accepted`:8283- if `notarytool submit` itself fails (credentials, network, service refusal), the first 8 lines of84 its error output are shown and the function fails;85- otherwise the `status` and `id` fields are read from the JSON answer and printed as86 `Submission <id>: <status>`;87- the notary log of that submission is fetched with `notarytool log` into88 `build/notary/<name>-log.json` (a failure to fetch the log is ignored);89- the function's result is the test `status == "Accepted"`.9091The header of the script states the rule this implements: the word "notarized" is printed only92when Apple's service answered Accepted.9394### Files written9596| File | Content |97|---|---|98| `build/notary/ORIXSheet-app.zip` | the archive uploaded for the app |99| `build/notary/app.json`, `build/notary/dmg.json` | JSON answer of each submission (id, status) |100| `build/notary/app.json.err`, `build/notary/dmg.json.err` | standard error of `notarytool submit` |101| `build/notary/app-log.json`, `build/notary/dmg-log.json` | the notary log of each submission |102| `dist/ORIXSheet-<version>.dmg`, `.zip`, `.sha256` | distribution artifacts |103104Source: `Scripts/notarize.sh`. `build/` and `dist/` are ignored by git (`.gitignore`).105106### Exit status and final messages107108| Exit | Meaning | Message |109|---|---|---|110| 0 | app and DMG accepted and stapled | `RESULT: … are notarized by Apple and stapled.` |111| 1 | `dist/ORIX Sheet.app` missing | `ERROR: … not found. Run Scripts/sign.sh first.` |112| 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 |113| 2 | the app submission was not accepted | `RESULT: NOT notarized. … is signed but carries no notarization ticket.` |114| 3 | the app is notarized and stapled, the DMG submission was not accepted | `RESULT: the app is notarized and stapled, the DMG is NOT.` |115116Source: `Scripts/notarize.sh`.117118## Gatekeeper checks119120Run by the script at the end, and usable by hand:121122```bash123spctl --assess --type execute --verbose=2 "dist/ORIX Sheet.app"124spctl --assess --type open --context context:primary-signature --verbose=2 "dist/ORIXSheet-1.0.0.dmg"125xcrun stapler validate "dist/ORIX Sheet.app"126xcrun stapler validate "dist/ORIXSheet-1.0.0.dmg"127```128129The script has no explicit test of the `spctl` answers, but it runs under `set -euo pipefail`: a130non-zero status from `spctl` (a rejected assessment) aborts the script with that pipeline's status131before the final `RESULT` line is printed. Read the two printed lines all the same; for a notarized132Developer ID build the expected source is "Notarized Developer ID".133134Not automated and not recorded as done: a first-launch test of the downloaded DMG on a second Mac135(quarantine attribute set by a browser), which is the only test of the full Gatekeeper path.136137## What to do on rejection1381391. **Read the log.** `build/notary/app-log.json` (or `dmg-log.json`) lists every issue with the path140 of the offending file inside the bundle. If it was not fetched:141 `xcrun notarytool log <submission-id> --keychain-profile "$NOTARY_PROFILE"`.142 `xcrun notarytool history --keychain-profile "$NOTARY_PROFILE"` lists past submissions.1432. **Map the issue to the signing step.** The checks of `Scripts/sign.sh` correspond to the usual144 causes:145146 | Notary issue | Check in this project |147 |---|---|148 | 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`) |149 | signature without a secure timestamp | every `codesign` call of `sign.sh` passes `--timestamp`; the build machine needs network access to Apple's timestamp server |150 | hardened runtime not enabled | the per-file `flags=…runtime` loop |151 | `get-task-allow` entitlement present | explicit check in `sign.sh`; `CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO` in `project.yml` |152 | a nested library signed by another team | the DuckDB case, see [signing](signing.md) |153154 Source: `Scripts/sign.sh`.1551563. **Fix, rebuild, re-sign.** Never patch a signed bundle: run `Scripts/sign.sh` again (it rebuilds157 and re-signs from scratch), then `Scripts/notarize.sh`.1584. **If the app was accepted and only the DMG failed (exit 3):** the app in `dist/` is already159 stapled. Re-running `notarize.sh` submits the app again before rebuilding the DMG; that is160 harmless but slow. The alternative is to run `Scripts/package.sh` and submit the DMG by hand161 with the same `notarytool submit … --wait` command.1625. **If `notarytool submit` itself fails:** check the profile name (`NOTARY_PROFILE`), that the163 profile exists in the keychain of the user running the script, and network access. Agreement164 updates on the developer account also block submissions; those need the account holder.165166## Limits167168- No timeout is passed to `--wait`; the script waits as long as the service takes.169- A submission uploads the application to Apple. It is the one release step that sends anything170 off the machine, and it needs the owner's credentials.171- The script does not record the accepted submission ids anywhere but `build/notary/`, which is not172 in git. Copy them into the release notes if they must be kept.173