@electron/notarize

What is @electron/notarize?

@electron/notarize is an npm package designed to help developers notarize their Electron applications for macOS. Notarization is a process by which Apple scans your app for malicious content and checks for code-signing issues. This package simplifies the process of submitting your app to Apple's notarization service and retrieving the results.

What are @electron/notarize's main functionalities?

Notarize an Electron App

This feature allows you to notarize your Electron application by providing the app bundle ID, the path to your app, and your Apple ID credentials. The function `notarize` handles the submission to Apple's notarization service.

const { notarize } = require('@electron/notarize');

async function notarizeApp() {
  await notarize({
    appBundleId: 'com.example.app',
    appPath: '/path/to/your/app.app',
    appleId: '[e-mail]',
    appleIdPassword: 'your-apple-id-password'
  });
}

notarizeApp().catch(console.error);

Check Notarization Status

This feature allows you to check the status of a notarization request by providing the request UUID and your Apple ID credentials. The function `checkNotarizationStatus` retrieves the current status of the notarization process.

const { checkNotarizationStatus } = require('@electron/notarize');

async function checkStatus(requestUUID) {
  const status = await checkNotarizationStatus({
    requestUUID,
    appleId: '[e-mail]',
    appleIdPassword: 'your-apple-id-password'
  });
  console.log(status);
}

checkStatus('your-request-uuid').catch(console.error);

Staple Notarization Ticket

This feature allows you to staple the notarization ticket to your Electron application. The function `stapleApp` ensures that the notarization ticket is attached to your app, which is required for distribution.

const { stapleApp } = require('@electron/notarize');

async function staple() {
  await stapleApp({
    appPath: '/path/to/your/app.app'
  });
}

staple().catch(console.error);

Other packages similar to @electron/notarize

electron-osx-sign

electron-osx-sign is a package that provides code-signing capabilities for macOS Electron applications. While it focuses on code-signing, it also offers notarization features. However, @electron/notarize is more specialized and streamlined for the notarization process.

electron-builder

electron-builder is a comprehensive package for building and packaging Electron applications. It includes features for code-signing and notarization, among many other functionalities. While it is more feature-rich, @electron/notarize is more focused and easier to use specifically for notarization tasks.

README

Electron Notarize

Notarize your Electron apps seamlessly for macOS

Installation

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.
2. An Apple Developer account.
3. An app-specific password for your ADC account’s Apple ID.
4. 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 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)
• 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.

Usage with app-specific password

You can generate an app-specific password for your Apple ID to notarize your Electron applications.

This method also requires you to specify the Team ID of the Developer Team you want to notarize under. An Apple ID may be part of multiple Teams.

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. 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.

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:

# App-specific password strategy
xcrun notarytool store-credentials "my-app-password-profile"
  --apple-id "<AppleID>"
  --team-id <DeveloperTeamID>
  --password <app_specific_password>

# 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.

import { notarize } from '@electron/notarize';

await notarize({
  appPath,
  keychainProfile,
});

Troubleshooting

Debug logging

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 will validate your credentials before even GitHub.

Validating app notarization

To validate that notarization worked, you can use the stapler command-line utility:

stapler validate path/to/notarized.app

Apple documentation

Apple also provides additional debugging documentation on Resolving common notarization issues.