starship/install/macos_packages/readme.md

MacOS Codesigning Scripts

Well, here we are. The Apple notarization procedure is complex enough that I need an actual pile of scripts and writeup to be able to remember how to do it.

The basic procedure is as follows:

• Build code
• Build docs
• Sign binary with Developer Application ID
• Upload binary to notarization service to get notarized
• Use code + docs to generate a component package
• Use component package to generate a distribution package
• Sign distribution package with Developer Installer ID
• Upload distribution package to notarization service to get notarized

Et. voila, you have a notarized distribution package which can be installed.

I fully anticipate that this procedure will break in the future, so here is the (scant) documentation that I have been able to scrape together on these procedures, along with some commentary on things that I've found and requirements for these scripts.

You will need XCode installed.

Short-form Command Line Invocation

If you have the prerequisites set up (including the environment variables as described below, built docs, and built release binary), you can generate the package file with the following command:

./install/macos_packages/build_and_notarize.sh target/release/starship docs x64

or arm64 if building on Apple silicon.

Setting Up Credentials

Apple Developer Account

In order to get the signing keys, you need to have a developer account. You can buy one at https://developer.apple.com/programs/ for $100 a year (at time of writing).

There is no other way to acquire an account, which is needed to obtain non-self-signed keys and to be able to notarize files.

Signing Keys

To generate the signing keys, I went through the XcodeGUI, though there are several other methods to do this. You will need at least one Application signing key and one Installer signing key.

To check what signing keys are available, you can use the following command:

security find-identity -p basic -v

Notarization Credentials

To be able to notarize objects, you will need an app-specific password. You will need to set it up using the instructions on this page. You will also need your team ID, which can be found at https://developer.apple.com/account/#/membership (if it goes to the home page, click on "Membership" on the left panel), and your Apple ID (usually an email address).

If you want to enter everything manually, most commands that require these values accept the --apple-id, --team-id, and --password flags. However, I find it simpler to store the credentials in the keychain. You can do so with the following command:

xcrun notarytool store-credentials "<AUTH_ITEM_NAME>" --apple-id "<apple-id>" --password "<password>" --team-id "<team-id>"

where <AUTH_ITEM_NAME> is a name you will use later to refer to the credentials, and the other three items are the Apple ID, the Team ID, and the app-specific password, respectively. For the rest of this document, I will assume that its value is AC_PASSWORD for compatibility with Apple's website, though you may choose whatever you like.

Script Assumptions

The scripts in this directory assume that the signing keys and the notarization credentials are unlocked and available within a specific keychain file, stored in a file at $RUNNER_TEMP/$KEYCHAIN_FILENAME. Additionally, it assumes that the AUTH_ITEM_NAME used to refer to the notarization credentials is found in the environment under the variable KEYCHAIN_ENTRY.

The CI environment ensures that the keychain file exists at the appropriate locations and is destroyed after use. If you are running these scripts locally, the values that correspond to what Apple uses in their tutorials are:

KEYCHAIN_ENTRY=AC_PASSWORD   # Or whatever you picked for <AUTH_ITEM_NAME> above
RUNNER_TEMP=~/Library/Keychains
KEYCHAIN_FILENAME=login.keychain

Note to developers: because the keychain file may be a user's personal keychain, you MUST NEVER WRITE TO THE KEYCHAIN FILE in these scripts. On the CI, CI actions will ensure that the keychain file is shredded after use.

Codesigning a Binary

This is actually fairly simple. Run

codesign --timestamp --sign "<Key ID>" --verbose -f -o runtime <binary>

to sign the binary file. --timestamp is not required for signing, but will be required for notarization. <Key ID> can be one of two things: the name of the signing key (on the right of security find-identity -p basic -v), or the key hash (the hex string on the left of the command).

Usually you can use name of the key, but if you have multiple keys like me, you may need to use the hex string to specify.

Notarizing a Binary

Once the binary has been signed, you need to package it into a .zip file in order to be able to send it to Apple for notarization. The simplest way to do this is to run zip <archive.zip> <binary>.

Then, run xcrun notarytool submit <archive.zip> --keychain-profile "AC_PASSWORD" --wait to submit the binary for notarization. The --wait flag will cause the tool to block until the notarialization is complete. If you want to be able to leave and check the results later, omit --wait (though starship notarization usually takes no more than 60s).

Finally, you should check the submission logs. To get a record of all notarization attempts, run

xcrun notarytool history --keychain-profile "AC_PASSWORD"

Find the id of the attempt you wish to view, then run one of these commmands:

xcrun notarytool info <run-id> --keychain-profile "AC_PASSWORD"
xcrun notarytool log <run-id> --keychain-profile "AC_PASSWORD"

The log command downloads a JSON log of the notarization attempt, and can reveal warnings that should be fixed before the next submission.

Additional details on the notarization process can be found at https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow. Note that while Apple has a lot of requirements on their pages, including stuff like Hardened Runtime requirements and listing entitlements, as far as I can tell, starship does not require any of these even though we do things like send notifications and access the network via an HTTP client. Nonetheless, I'm linking the entitlements page here in case it becomes important later.

Creating a Component Package

Since I'm only dealing with one binary, we will make one Component package and one Distribution package. Surprisingly, the flat package (.pkg) format is not documented by Apple. This guide and many of the links within it are the best documentation available on the subject.

To build a component package, we first need to create a temporary directory and create a pseudo-filesystem within it (similar to makepkg on Arch). For example, if we place the directory at $TEMP_DIR/usr/local/bin/starship, the binary will be installed at /usr/local/bin/starship once the installer runs.

An aside on docs: We would also like to include documentation in the pkg. Unfortunately, Vuepress currently cannot build with relative paths, and any attempt at hacking this in seems to create even more problems. Instead, the scripts do the dumbest thing imaginable: build the documentation, serve it with a simple HTTP server, and then use wget to make a local copy which can be viewed offline.

Once everything is placed in the correct locations, we can run the following command to generate the component package:

pkgbuild --identifier com.starshipprompt.starship --version "<version>" --root <pkgdir> output.pkg

Notarizing the Component Package (and why we don't need to)

Fortunately for us, Apple has confirmed that we only need to notarize the outermost installer mechanism.

Therefore, if we are sending the component package on its own, we should notarize it now. However, for starship, we will bundle this into a distribution package, so we don't need to notarize this pkg file.

Creating a Distribution Package

To create a distribution, we do the following steps:

• Use productbuild to generate a skeleton distribution file.
• Insert custom welcome/license/conclusion and icon files into the installer.
• Build the installer with productbuild.

I have elected not to make a fat binary due to concerns over startup cost, so there are two .plist files that can be used to specify the architecture required.

Signing the Distribution package

This is also fairly simple, and analagous to signing the binary.

productsign --timestamp --sign "<Key ID>" <input.pkg> <output.pkg>

Notarizing the Distribution Package

Also analagous to notarizing the binary. We run

xcrun notarytool submit <package.pkg> --keychain-profile "AC_PASSWORD" --wait

and also check the submission logs.

Note: you may need to enter your password a ridiculous number of times (like 4+) in order to successfully notarize this.

Stapling the Result

Finally, we staple the notarization ticket to the package, ensuring that anyone who downloads the file can see that the installer was notarized:

xcrun stapler staple <package>

Note that .dmg, .app, and .pkg files can be stapled, but .zip and binary files cannot. Distributing the latter files alone will require that the installing computer can access the internet to verify notarization of the app.

Putting It All Together

If you don't want to run these commands, a full workflow is available in build_and_notarize script. Check the documentation at the top of the script for environment variables and arguments that need to be set--it is a fairly complicated script, but this is a fairly complicated procedure.

Testing Notarization

To test if a particular item is notarized, run one of the following commands:

codesign --test-requirement="=notarized" --verify --verbose <file>
spctl -a -vvv -t install <file>

External Links

https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution

https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow

https://github.com/akeru-inc/xcnotary

https://www.reddit.com/r/rust/comments/q8r90b/notarization_of_rust_binary_for_distribution_on/