1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
Electron Notarize
-----------
> Notarize your Electron apps seamlessly for macOS
[](https://circleci.com/gh/electron/notarize)
[](https://npm.im/@electron/notarize)
## Installation
```bash
# npm
npm install @electron/notarize --save-dev
# yarn
yarn add @electron/notarize --dev
```
## What is app "notarization"?
From Apple's docs in XCode:
> A notarized app is a macOS app that was uploaded to Apple for processing before it was distributed. When you export a notarized app from Xcode, it code signs the app with a Developer ID certificate and staples a ticket from Apple to the app. The ticket confirms that you previously uploaded the app to Apple.
> On macOS 10.14 and later, the user can launch notarized apps when Gatekeeper is enabled. When the user first launches a notarized app, Gatekeeper looks for the app’s ticket online. If the user is offline, Gatekeeper looks for the ticket that was stapled to the app.
Apple has made this a hard requirement as of 10.15 (Catalina).
## Prerequisites
For notarization, you need the following things:
1. Xcode 10 or later installed on your Mac.
2. An [Apple Developer](https://developer.apple.com/) account.
3. [An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).
4. Your app may need to be signed with `hardened-runtime`, including the following entitlement:
1. `com.apple.security.cs.allow-jit`
If you are using Electron 11 or below, you must add the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement too.
When using version 12+, this entitlement should not be applied as it increases your app's attack surface.
## API
### Method: `notarize(opts): Promise<void>`
* `options` Object
* `tool` String - The notarization tool to use, default is `legacy`. Can be `legacy` or `notarytool`. `notarytool` is substantially (10x) faster.
* `appPath` String - The absolute path to your `.app` file
* There are different options for each tool: Legacy
* `appBundleId` String - The app bundle identifier your Electron app is using. E.g. `com.github.electron`
* `ascProvider` String (optional) - Your [Team Short Name](#notes-on-your-team-short-name).
* There are two authentication methods available: user name with password:
* `appleId` String - The username of your apple developer account
* `appleIdPassword` String - The [app-specific password](https://support.apple.com/HT204397) (not your Apple ID password).
* ... or apiKey with apiIssuer:
* `appleApiKey` String - Required for JWT authentication. See Note on JWT authentication below.
* `appleApiIssuer` String - Issuer ID. Required if `appleApiKey` is specified.
* ... or Notary Tool
* There are three authentication methods available: user name with password:
* `appleId` String - The username of your apple developer account
* `appleIdPassword` String - The [app-specific password](https://support.apple.com/HT204397) (not your Apple ID password).
* `teamId` String - The team ID you want to notarize under.
* ... or apiKey with apiIssuer:
* `appleApiKey` String - Required for JWT authentication. See Note on JWT authentication below.
* `appleApiKeyId` String - Required for JWT authentication. See Note on JWT authentication below.
* `appleApiIssuer` String - Issuer ID. Required if `appleApiKey` is specified.
* ... or keychain with keychainProfile:
* `keychain` String - The name of the keychain or path to the keychain you stored notarization credentials in.
* `keychainProfile` String - The name of the profile you provided when storing notarization credentials.
## Safety when using `appleIdPassword`
1. Never hard code your password into your packaging scripts, use an environment
variable at a minimum.
2. It is possible to provide a keychain reference instead of your actual password (assuming that you have already logged into
the Application Loader from Xcode). For example:
```javascript
const password = `@keychain:"Application Loader: ${appleId}"`;
```
Another option is that you can add a new keychain item using either the Keychain Access app or from the command line using the `security` utility:
```bash
security add-generic-password -a "AC_USERNAME" -w <app_specific_password> -s "AC_PASSWORD"
```
where `AC_USERNAME` should be replaced with your Apple ID, and then in your code you can use:
```javascript
const password = `@keychain:AC_PASSWORD`;
```
## Notes on JWT authentication
You can obtain an API key from [Appstore Connect](https://appstoreconnect.apple.com/access/api). Create a key with _App Manager_ access. Note down the Issuer ID and download the `.p8` file. This file is your API key and comes with the name of `AuthKey_<api_key>.p8`. This is the string you have to supply when calling `notarize`.
Based on the `ApiKey`, `altool` will look in the following places for that file:
* `./private_keys`
* `~/private_keys`
* `~/.private_keys`
* `~/.appstoreconnect/private_keys`
## Notes on your Team Short Name
If you are a member of multiple teams or organizations, you have to tell Apple on behalf of which organization you're uploading. To find your [team's short name](https://forums.developer.apple.com/thread/113798)), you can ask `iTMSTransporter`, which is part of the now deprecated `Application Loader` as well as the newer [`Transporter`](https://apps.apple.com/us/app/transporter/id1450874784?mt=12).
With `Transporter` installed, run:
```sh
/Applications/Transporter.app/Contents/itms/bin/iTMSTransporter -m provider -u APPLE_DEV_ACCOUNT -p APP_PASSWORD
```
Alternatively, with older versions of Xcode, run:
```sh
/Applications/Xcode.app/Contents/Applications/Application Loader.app/Contents/itms/bin/iTMSTransporter -m provider -u APPLE_DEV_ACCOUNT -p APP_PASSWORD
```
## Example Usage
```javascript
import { notarize } from '@electron/notarize';
async function packageTask () {
// Package your app here, and code sign with hardened runtime
await notarize({
appBundleId,
appPath,
appleId,
appleIdPassword,
ascProvider, // This parameter is optional
});
}
```
|
