ScreenPlay/Docs/macOSSigning.md

# ScreenPlay macOS signing full guide

## Create a developer account and certs
1. Pay the 99$ Apple tax
2. Create a app password for distribution outside of the app store
- Go to https://appleid.apple.com/account/manage
- Call it ScreenPlay and save the password!

## Add a new device
Based on: https://developer.apple.com/forums/thread/699268

1. You run Keychain Access and choose Certificate Assistant > Request a Certificate from a Certificate Authority.
1. You run through the workflow as described in Developer [Account Help > Create certificates > Create a certificate signing](https://help.apple.com/developer-account/#/devbfa00fef7) request. This does two things:
    - It generates a public / private key pair in your keychain. To see these, run Keychain Access and select “login” on the left and Keys at the top. Look for keys whose names match the Common Name you entered in step 2.
    - It prompts you to save a .certSigningRequest file (CSR). This contains a copy of the public key.
1. You upload the CSR file to the [developer web site](https://developer.apple.com/account/resources/certificates/list). Select `Developer ID Application` and upload your new `CertificateSigningRequest.certSigningRequest`.
1. The developer web site issues you a certificate. In human terms this certificate says “Apple certifies that the subject of this certificate holds the private key that matches the public key embedded in this certificate.”

> Note The developer web site sets the subject information in the certificate based on your developer account. It ignores the subject information in the CSR. So, you can enter any information you want in step 2. This is a good way to distinguish between different keys in your keychain. For example, you might set the Common Name field in step 2 to include a unique identifier that allows you to easily identify the public / private key pair generated in step 3.

5. Download the certificate and add it to your keychain.

## Testing 
There should be at least one valid identity:
```
security find-identity -p codesigning -v
```

should print:

```
1) xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "Developer ID Application: Elias Steurer (V887LHYKRH)"
     1 valid identities found
```

## Sign the app locally with codesign
We need to sign every single file in the .app file. For this we use the name from the installed cert. This can be copied from the `Keychain Access.app`.

```
codesign --deep -f -s "Developer ID Application: Elias Steurer (V887LHYKRH)" --options "runtime" "ScreenPlay.app/"
```

## Add App Store Connect API private key:
- [Create Private Key](https://appstoreconnect.apple.com/access/users)
- Save private key as a file, KEY ID, Issuer ID. We need them next:

```
xcrun notarytool  store-credentials
```

1. Profile name: 
    - Profile name: ScreenPlay
2. Path to App Store Connect API private key:
    - Path to App Store Connect API private key: `/Users/eliassteurer/Documents/AuthKey_xxxxxxx.p8`
3. App Store go to : https://appstoreconnect.apple.com/access/api
    - Klick Keys in the top menu. Then you can answer the next two questions:
    - App Store Connect API Key ID: There is a list of `Active` names, generated by. Use this `KEY ID`
    - App Store Connect API Issuer ID: Then copy the `Issuer ID` above it
    - __IMPORTANT__: The Profile name must match the one set in:
    ```xcrun notarytool submit ScreenPlay.app.zip --keychain-profile 'ScreenPlay' --wait```

Example output:
```
eliassteurer@Eliass-Mac-mini Tools % xcrun notarytool  store-credentials

This process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.

Profile name:
xxxxxxx
We recommend using App Store Connect API keys for authentication. If you'd like to authenticate with an Apple ID and app-specific password instead, leave this unspecified.

Path to App Store Connect API private key:
/Users/xxxxxxxxxx/Documents/AuthKey_xxxxxxxxxxx.p8
App Store Connect API Key ID:
ScreenPlay
App Store Connect API Issuer ID:
xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Validating your credentials...
Success. Credentials validated.
Credentials saved to Keychain.
To use them, specify `--keychain-profile "xxxxxxx"`
eliassteurer@Eliass-Mac-mini Tools % --keychain-profile "ScreenPlay"
```

## Add your credentials to the system:
See: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow
```
xcrun notarytool store-credentials "ScreenPlay"
               --apple-id "AC_USERNAME"
               --team-id <WWDRTeamID>
               --password <secret_2FA_password>
```
- `AC_USERNAME` = Your email or something you set at AppleID (email): https://appleid.apple.com/account/manage/section/security
https://stackoverflow.com/questions/56890749/macos-notarize-in-script
- `WWDRTeamID` = Go to https://appstoreconnect.apple.com/access/users click on your listed user and copy the `xxxxxxx` from:
```
Team ID
XXXXXXXXXX View Membership Details
```
- `password` = Go to https://appleid.apple.com/account/manage/section/security then to `App-specific passwords` and use this password. This will not display you the password, but you can simply remove it, generate a new under the same name and copy the displayed password.

## Get an App-Specific Password
https://stackoverflow.com/questions/56890749/macos-notarize-in-script
```
security add-generic-password -a "kelteseth@gmail.com" -w "xxxx-xxx-xxx-xxx" -s "Developer ID Application: Elias Steurer (V887LHYKRH)"
```

## FAQ Troubleshooting
```
Processing complete
id: xxxxxx-xxxxxx-xxxx-xxxxx-xxxxx
status: Invalid
```
Run the follwoing if you get an signing error:
`xcrun notarytool log --apple-id "xxxxx@xxxx.com" --password "xxxx-xxxx-xxxx-xxxx" --team-id "xxxxxxxxxxx"  <ID>`


```
Error: HTTP status code: 403. A required agreement is missing or has expired. This request requires an in-effect agreement that has not been signed or has expired. Ensure your team has signed the necessary legal agreements and that they are not expired.
```

Go to [appstoreconnect.apple.com](https://appstoreconnect.apple.com) and accept the updated  'Apple Developer Program License Agreement'.