yubioath-flutter/doc/MacOS_Packaging.adoc

== Packaging for MacOS
Building the Helper locally will result in an adhoc-signed build, which works
for local development, but not for distribution. Before distributing it needs
to be re-signed. Build the Helper by running `build-helper.sh`, see the main
README for details.

To distribute the app you will need the Yubico MacOS signing key. The method of
signing differs depending on if the app should be distributed standalone
(outside the App Store) or via the App Store.


=== Standalone (Notarized)
To distribute the app outside of the App Store, we need to sign it and Notarize
it. For Notarization to work, we must enable "hardened runtime" by setting the
`--options runtime` when signing.

==== Signing the Yubico Authenticator Helper
The following commands can be done to re-sign the files using the Yubico
signing key:

  # Sign the main binaries, with the entitlements:
  codesign -f --timestamp --options runtime --entitlements helper.entitlements --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper/authenticator-helper

  codesign -f --timestamp --options runtime --entitlements helper.entitlements --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper-arm64/authenticator-helper

  # Sign the dylib and so files, without entitlements:
  codesign -f --timestamp --options runtime --sign 'Application' $(find Yubico\ Authenticator.app/Contents/Resources/helper/ -name "*.dylib" -o -name "*.so")

  codesign -f --timestamp --options runtime --sign 'Application' $(find Yubico\ Authenticator.app/Contents/Resources/helper-arm64/ -name "*.dylib" -o -name "*.so")

  # Sign the Python binary (if it exists), without entitlements:
  codesign -f --timestamp --options runtime --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper/Python

  codesign -f --timestamp --options runtime --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper-arm64/Python

==== Signing the GUI
After signing the Helper, make a release build of the GUI and then re-sign it
with the Yubico key:

  codesign --timestamp --options runtime --sign 'Application' --entitlements Release.entitlements --deep "Yubico Authenticator.app"

The app should now be properly signed, and needs to be Notarized. Create a zip file with the .app, and:

  xcrun altool -t osx -f app.zip --primary-bundle-id com.yubico.authenticator --notarize-app -u $APPLE_ID -p $PASSWORD

This will return a $APP_GUID.

To check if notarization is complete:

  xcrun altool --notarization-info $APP_GUID -u $APPLE_ID -p $PASSWORD

When the notarization is complete, and successful, the original .app bundle (not the .zip archive) needs to be stapled.

  xcrun stapler staple -v "Yubico Authenticator.app"

Everything has now been signed and we can create a dmg.

==== Creating a dmg
Create a directory called `source_folder` and move the .app to it.
Install `create-dmg` by running `brew install create-dmg`.
Run the `create-dmg.sh` script.

=== Signing for the App Store
All binaries must have sandbox enabled for the Apple App Store, but the Helper
binary doesn't work when sandboxed AND hardened. Luckily, App Store binaries do
not need to be hardened. Thus, we need to sign the Helper executable with
sandbox enabled, but NOT as a hardened build. The App Store build also uses a
different code signing key than the standalone distribution.

==== Signing the Yubico Authenticator Helper
Follow the same steps as for "standalone", with the exception of signing the `authenticator-helper` binary:

  # Sign the main binaries, with sandbox enabled, without hardened runtime:
  codesign -f --timestamp --entitlements helper-sandbox.entitlements --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper/authenticator-helper

  codesign -f --timestamp --entitlements helper-sandbox.entitlements --sign 'Application' Yubico\ Authenticator.app/Contents/Resources/helper-arm64/authenticator-helper

NOTE: This sandboxed Helper will not run on its own, it has to be run as a
subprocess to the main application.

Once you have the signed .app, (no Notarization required) build the package for AppStore submission:

  productbuild --sign 'Installer' --component "Yubico Authenticator.app" /Applications/ output-appstore.pkg

Use the Transporter app to upload the package to Apple.