add macOS docs

macos.bash

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+
+# This file provides support functionality for signing and notarising mac
+# distributables.
+
+# Codesigning (macOS)
+# ===================
+#
+# macOS will reject executables that are not codesigned.  As such we need to
+# sign them.  For this a Developer ID and signing certificate is required.  This
+# can be obtained even with a free developer account at 
+# https://developer.apple.com/account/resources/certificates/list
+# It will also require the `codesign` executable.  If signing fails, you may
+# need to install the 
+#
+#  > Apple Worldwide Developer Relations Certification Authority
+#
+# intermediate certificate, which can be downloaded from apples developer
+# portal.
+#
+# For codesigning (executables and libraries), we can use
+#
+#  > security find-identity -v -p codesigning
+#
+# to find available code signing identities.  And then use 
+#
+#  > codesign --force \
+#             --options runtime \
+#             --timestamp \
+#             --sign "Developer ID Application: John Doe (XXXXXXXXXX)" \
+#             FILE
+#
+
+# Packaging (macOS)
+# =================
+# There are multiple ways to package software for macOS.  The simplest is a zip
+# archive using `ditto`, we then also have installable `pkg`s, and mountable
+# `dmg` disk images.
+#
+# Zip archive
+# -----------
+# After sigining the executables, we use `ditto` to create the relevant .zip
+# file.
+# 
+#  > ditto -c -k --sequesterRsrc --zlibCompressionLevel 9 x y z pkg.zip
+#
+
+# Notarisation (macOS)
+# ====================
+#
+# While a codesigned binary contains some trust that it originated with us, we
+# need to have apple notarise it, so that gatekeeper will just happily accept
+# it.  To do this, we could use notarytool form xcode, or the REST API that
+# apple provides.  We'll opt for the REST API, as that doesn't require us to
+# download and install xcode.
+#
+# For this we need to have an appstoreconnect credentials.  These can be
+# obtained again from apple at https://appstoreconnect.apple.com/access/api.
+# 
+# We require curl, awscli, jq and and jwt-cli
+#
+# There will be a Key Identifier on the access/api page, in the form of
+# 2X9R4HXF34, and a one-time option to download the associated
+# AuthKey_2X9R4HXF34.p8 assoicated key with it. We'll also need the
+# ISSuer ID, which looks like 57246542-96fe-1a63-e053-0824d011072a.
+#
+# With his we can then create the Json Web Token (JWT) as follows:
+#
+# > jwt encode --alg ES256 \
+#              --aud appstoreconnect-v1 \
+#              --kid 2X9R4HXF34 \
+#              --exp $(date -d "now + 300 seconds" +%s) \
+#              --payload 'scope=["POST /notary/v2/submissions", "GET /notary/v2/submissions"]' \
+#              --payload iss=0d0b2b08-352f-410b-b9b4-af0b1c6592a8 \
+#              --secret @<(cat AuthKey_2X9R4HXF34.p8 | grep -v "PRIVATE KEY" | base64 -d)
+#
+# Using curl, we can check for past submissing:
+#
+#  > curl -v -H "Authorization: Bearer <token>" "https://appstoreconnect.apple.com/notary/v2/submissions"
+#
+# To create a new one, we need the sha256 and name for what ever we want to
+# notarise.  E.g. the .zip file we created with `ditto` above.
+#
+#  > read -r SHA NAME < <(sha256sum pkg.zip)
+#
+# With the JWT token written to e.g. $JWT, we can then
+#
+#  >  curl -H "Authorization: Bearer $JWT" \
+#          -H 'Content-Type: application/json' \
+#          -X POST https://appstoreconnect.apple.com/notary/v2/submissions \
+#          -d '{"sha256":"$SHA", "submissionName": "$NAME"}'
+#
+# This will return some JSON of the form
+#
+#  { "data":
+#    { "type": "newSubmissions"
+#    , "id": "15041285-....-....-....-............"
+#    , "attributes":
+#      { "awsAccessKeyId": "..."
+#      , "awsSecretAccessKey": "..."
+#      , "awsSessionToken": "..."
+#      , "bucket": "notary-submissions-prod"
+#      , "object": "prod/..."} }
+#  , "meta": {}}
+#
+# Which we can then use with `awscli` as follows:
+#
+#  > AWS_ACCESS_KEY_ID="$awsAccessKeyId" \
+#    AWS_SECRET_ACCESS_KEY="$awsSecretAccessKey" \
+#    AWS_SESSION_TOKEN="$awsSessionToken" \
+#    aws s3 cp pkg.zip s3://$bucket/$object
+#
+# Once this is done, we can perodically poll the newSubmissions endpoint to see
+# if notarisation has succeeded.
+#