main funcions fixes
This commit is contained in:
190
desktop-operator/node_modules/@electron/notarize/README.md
generated
vendored
Normal file
190
desktop-operator/node_modules/@electron/notarize/README.md
generated
vendored
Normal file
@@ -0,0 +1,190 @@
|
||||
Electron Notarize
|
||||
-----------
|
||||
|
||||
> Notarize your Electron apps seamlessly for macOS
|
||||
|
||||
[](https://circleci.com/gh/electron/notarize)
|
||||
[](https://npm.im/@electron/notarize)
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @electron/notarize --save-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.
|
||||
|
||||
As macOS 10.15 (Catalina), Apple has made notarization a hard requirement for all applications
|
||||
distributed outside of the Mac App Store. App Store applications do not need to be notarized.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
For notarization, you need the following things:
|
||||
|
||||
1. Xcode 13 or later installed on your Mac.
|
||||
1. An [Apple Developer](https://developer.apple.com/) account.
|
||||
1. [An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).
|
||||
1. Your app may need to be signed with `hardenedRuntime: true` option, with the `com.apple.security.cs.allow-jit` entitlement.
|
||||
|
||||
> [!NOTE]
|
||||
> 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.
|
||||
|
||||
### Notarization on older macOS versions
|
||||
|
||||
Xcode 13 is available from macOS 11.3, but notarization can be performed on systems down to macOS 10.15
|
||||
(see [TN3147](https://developer.apple.com/documentation/technotes/tn3147-migrating-to-the-latest-notarization-tool#Enable-notarization-on-an-older-version-of-macOS) for more information).
|
||||
|
||||
To achieve this, you can copy notarytool binary from a newer macOS version and provide its path as `notarytoolPath` option.
|
||||
|
||||
## API
|
||||
|
||||
`@electron/notarize` exposes a single `notarize` function that accepts the following parameters:
|
||||
* `appPath` — the absolute path to your codesigned and packaged Electron application.
|
||||
* `notarytoolPath` - String (optional) - Path of the notarytool binary ([more details](#notarization-on-older-macos-versions))
|
||||
* additional options required for authenticating your Apple ID (see below)
|
||||
|
||||
The method returns a void Promise once app notarization is complete. Please note that notarization may take
|
||||
many minutes.
|
||||
|
||||
If the notarization process is unusually log for your application, see Apple Developer's docs to
|
||||
[Avoid long notarization response times and size limits](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow#3561440).
|
||||
|
||||
### Usage with app-specific password
|
||||
|
||||
You can generate an [app-specific password](https://support.apple.com/en-us/102654) for your Apple ID
|
||||
to notarize your Electron applications.
|
||||
|
||||
This method also requires you to specify the [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)
|
||||
of the Developer Team you want to notarize under. An Apple ID may be part of multiple Teams.
|
||||
|
||||
```javascript
|
||||
import { notarize } from '@electron/notarize';
|
||||
|
||||
await notarize({
|
||||
appPath,
|
||||
appleId, // Login name of your Apple Developer account
|
||||
appleIdPassword, // App-specific password
|
||||
teamId, // Team ID for your developer team
|
||||
});
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Never hard code your app-specific password into your packaging scripts.** Use an environment
|
||||
> variable at a minimum.
|
||||
|
||||
### Usage with App Store Connect API key
|
||||
|
||||
Alternatively, you can also authenticate via JSON Web Token (JWT) with App Store Connect.
|
||||
|
||||
You can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api).
|
||||
Create a **Team Key** (not an _Individual Key_) with **App Manager** access.
|
||||
|
||||
Note down the Issuer ID (UUID format) and Key ID (10-character alphanumeric string),
|
||||
and download the `.p8` API key file (`AuthKey_<appleApiKeyId>.p8`).
|
||||
For security purposes, the private key can only be downloaded once.
|
||||
|
||||
Provide the absolute path to your API key as the `appleApiKey` argument.
|
||||
|
||||
```javascript
|
||||
import { notarize } from '@electron/notarize';
|
||||
|
||||
await notarize({
|
||||
appPath,
|
||||
appleApiKey, // Absolute path to API key (e.g. `/path/to/AuthKey_X0X0X0X0X0.p8`)
|
||||
appleApiIssuer, // Issuer ID (e.g. `d5631714-a680-4b4b-8156-b4ed624c0845`)
|
||||
});
|
||||
```
|
||||
|
||||
### Usage with Keychain credentials
|
||||
|
||||
As an alternative to passing authentication options, you can also store your authentication
|
||||
credentials (for both API key and app-specific password strategies) in the macOS Keychain
|
||||
via the `xcrun notarytool` command-line utility.
|
||||
|
||||
This method has the advantage of validating your notarization credentials before submitting
|
||||
your application for notarization.
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
# App-specific password strategy
|
||||
xcrun notarytool store-credentials "my-app-password-profile"
|
||||
--apple-id "<AppleID>"
|
||||
--team-id <DeveloperTeamID>
|
||||
--password <app_specific_password>
|
||||
```
|
||||
|
||||
```sh
|
||||
# App Store Connect API key strategy
|
||||
xcrun notarytool store-credentials "my-api-key-profile"
|
||||
--key "<PathToAPIKey>"
|
||||
--key-id <KeyID>
|
||||
--issuer <IssuerID>
|
||||
```
|
||||
|
||||
Successful storage of your credentials will look like this:
|
||||
|
||||
```
|
||||
This process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.
|
||||
|
||||
Validating your credentials...
|
||||
Success. Credentials validated.
|
||||
Credentials saved to Keychain.
|
||||
To use them, specify `--keychain-profile "my-api-key-profile"`
|
||||
```
|
||||
|
||||
After successfully storing your credentials, pass the keychain profile name into
|
||||
the `keychainProfile` parameter.
|
||||
|
||||
```javascript
|
||||
import { notarize } from '@electron/notarize';
|
||||
|
||||
await notarize({
|
||||
appPath,
|
||||
keychainProfile,
|
||||
});
|
||||
```
|
||||
## Troubleshooting
|
||||
|
||||
### Debug logging
|
||||
|
||||
[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages.
|
||||
Run your notarization scripts with the `DEBUG=electron-notarize*` environment variable to log additional
|
||||
debug information from this module.
|
||||
|
||||
### Validating credentials
|
||||
|
||||
When notarizing your application, you may run into issues with validating your notarization
|
||||
credentials.
|
||||
|
||||
```
|
||||
Error: HTTP status code: 401. Invalid credentials. Username or password is incorrect.
|
||||
Use the app-specific password generated at appleid.apple.com. Ensure that all authentication arguments are correct.
|
||||
```
|
||||
|
||||
[Storing your credentials in Keychain](#usage-with-keychain-credentials) will validate your credentials before
|
||||
even GitHub.
|
||||
|
||||
### Validating app notarization
|
||||
|
||||
To validate that notarization worked, you can use the `stapler` command-line utility:
|
||||
|
||||
```sh
|
||||
stapler validate path/to/notarized.app
|
||||
```
|
||||
|
||||
### Apple documentation
|
||||
|
||||
Apple also provides additional debugging documentation on
|
||||
[Resolving common notarization issues](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues).
|
||||
Reference in New Issue
Block a user