@electron/notarize - npm Package Compare versions

Comparing version 2.3.2 to 2.4.0

lib/check-signature.d.ts

@@ -1,2 +0,2 @@
-import { NotarizeStapleOptions } from './types';
-export declare function checkSignatures(opts: NotarizeStapleOptions): Promise<void>;
+import { NotaryToolNotarizeAppOptions } from './types';
+export declare function checkSignatures(opts: NotaryToolNotarizeAppOptions): Promise<void>;

lib/index.d.ts

 import { NotarizeOptions, NotarizeOptionsLegacy, NotarizeOptionsNotaryTool } from './types';
 export { NotarizeOptions };
 export { validateNotaryToolAuthorizationArgs as validateAuthorizationArgs } from './validate-args';
+/**
+ * Sends your app to Apple for notarization with `notarytool` and staples a successful
+ * notarization result to the app bundle. This includes your {@link NotaryToolNotarizeAppOptions.appPath | appPath}
+ * as well as one of three valid credential authentication strategies.
+ *
+ * See {@link NotaryToolCredentials} for authentication options.
+ *
+ * @category Core
+ * @param args Options for notarization
+ * @returns The Promise resolves once notarization is complete. Note that this may take a few minutes.
+ */
 declare function notarize(args: NotarizeOptionsNotaryTool): Promise<void>;
-/** @deprecated */
+/**
+ * @deprecated
+ */
 declare function notarize(args: NotarizeOptionsLegacy): Promise<void>;
 export { notarize };

lib/notarytool.js

@@ -75,2 +75,14 @@ "use strict";
 }
+function getNotarizationLogs(opts, id) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const logResult = yield (0, spawn_1.spawn)('xcrun', ['notarytool', 'log', id, ...authorizationArgs(opts)]);
+            d('notarization log', logResult.output);
+            return logResult.output;
+        }
+        catch (e) {
+            d('failed to pull notarization logs', e);
+        }
+    });
+}
 function isNotaryToolAvailable() {
@@ -122,22 +134,10 @@ return __awaiter(this, void 0, void 0, function* () {
             }
+            let logOutput;
+            if (typeof parsed.id === 'string') {
+                logOutput = yield getNotarizationLogs(opts, parsed.id);
+            }
             if (result.code === 0 && parsed.status === 'Accepted') {
-                d('notarization success');
+                d(`notarization success (id: ${parsed.id})`);
                 return;
             }
-            let logOutput;
-            if (parsed.id) {
-                try {
-                    const logResult = yield (0, spawn_1.spawn)('xcrun', [
-                        'notarytool',
-                        'log',
-                        parsed.id,
-                        ...authorizationArgs(opts),
-                    ]);
-                    d('notarization log', logResult.output);
-                    logOutput = logResult.output;
-                }
-                catch (e) {
-                    d('failed to pull notarization logs', e);
-                }
-            }
             let message = `Failed to notarize via notarytool\n\n${result.output}`;
@@ -144,0 +144,0 @@ if (logOutput) {

lib/staple.d.ts

@@ -1,2 +0,2 @@
-import { NotarizeStapleOptions } from './types';
-export declare function stapleApp(opts: NotarizeStapleOptions): Promise<void>;
+import { NotaryToolNotarizeAppOptions } from './types';
+export declare function stapleApp(opts: NotaryToolNotarizeAppOptions): Promise<void>;

lib/types.d.ts

@@ -1,2 +0,5 @@
-/** @deprecated */
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export interface LegacyNotarizePasswordCredentials {
@@ -6,8 +9,34 @@ appleId: string;
 }
+/**
+ * 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.
+ *
+ * @category Credential Strategies
+ */
 export interface NotaryToolPasswordCredentials {
+    /**
+     * The login username of your Apple Developer account.
+     */
     appleId: string;
+    /**
+     * An [app-specific password](https://support.apple.com/en-us/102654) for your
+     * Apple ID (**not** your Apple ID password).
+     *
+     * Do **not** hard code this password into your packaging scripts.
+     */
     appleIdPassword: string;
+    /**
+     * The [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)
+     * for the Developer Team you want to notarize under. Your Apple ID may be a member of multiple
+     * teams.
+     */
     teamId: string;
 }
-/** @deprecated */
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export interface LegacyNotarizeApiKeyCredentials {
@@ -17,16 +46,63 @@ appleApiKey: string;
 }
+/**
+ * Credentials required for JSON Web Token (JWT) notarization using App Store Connect API keys.
+ *
+ * @category Credential Strategies
+ */
 export interface NotaryToolApiKeyCredentials {
+    /**
+     * File system path to the `.p8` private key of your App Store Connect API key.
+     */
     appleApiKey: string;
+    /**
+     * App Store Connect API Key ID (e.g. `T9GPZ92M7K`).
+     *
+     */
     appleApiKeyId: string;
+    /**
+     * App Store Connect API Issuer ID. The issuer ID is a UUID format string
+     * (e.g. `c055ca8c-e5a8-4836-b61d-aa5794eeb3f4`).
+     */
     appleApiIssuer: string;
 }
+/**
+ * Options required for authenticating notarytool by storing
+ * credentials inside the system Keychain item.
+ *
+ * You can store {@link NotaryToolPasswordCredentials} or
+ * {@link NotaryToolApiKeyCredentials} into the Keychain
+ * using `xcrun notarytool store-credentials` and access the
+ * stored secrets when signing your code.
+ *
+ * @category Credential Strategies
+ */
 export interface NotaryToolKeychainCredentials {
+    /**
+     * The name of the profile you provided when storing notarization credentials.
+     */
     keychainProfile: string;
+    /**
+     * The name of the keychain or path to the keychain you stored notarization credentials in.
+     * @defaultValue If omitted, the system default `login` keychain will be used.
+     */
     keychain?: string;
 }
-/** @deprecated */
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export type LegacyNotarizeCredentials = LegacyNotarizePasswordCredentials | LegacyNotarizeApiKeyCredentials;
+/**
+ * Credential options for authenticating `notarytool`. There are three valid stategies available:
+ *
+ * - {@link NotaryToolPasswordCredentials} — Using an Apple ID and app-specific password
+ * - {@link NotaryToolApiKeyCredentials} — Using an App Store Connect API key
+ * - {@link NotaryToolKeychainCredentials} — Using one of the two above credential sets stored within the macOS Keychain
+ * @category Credential Strategies
+ */
 export type NotaryToolCredentials = NotaryToolPasswordCredentials | NotaryToolApiKeyCredentials | NotaryToolKeychainCredentials;
-export type NotarizeCredentials = LegacyNotarizeCredentials | NotaryToolCredentials;
-/** @deprecated */
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export interface LegacyNotarizeAppOptions {
@@ -36,24 +112,60 @@ appPath: string;
 }
+/**
+ * Non-credential options for notarizing your application with `notarytool`.
+ * @category Core
+ */
 export interface NotaryToolNotarizeAppOptions {
+    /**
+     * Absolute path to your packaged and codesigned Electron application.
+     */
     appPath: string;
 }
-export interface TransporterOptions {
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
+interface TransporterOptions {
     ascProvider?: string;
 }
-export interface NotarizeResult {
+/**
+ * @deprecated This interface was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
+interface NotarizeResult {
     uuid: string;
 }
-/** @deprecated */
+/**
+ * @deprecated This type was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export type LegacyNotarizeStartOptions = LegacyNotarizeAppOptions & LegacyNotarizeCredentials & TransporterOptions;
-export type NotaryToolStartOptions = NotaryToolNotarizeAppOptions & NotaryToolCredentials;
-/** @deprecated */
+/**
+ * @deprecated This type was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export type LegacyNotarizeWaitOptions = NotarizeResult & LegacyNotarizeCredentials;
-export type NotarizeStapleOptions = Pick<LegacyNotarizeAppOptions, 'appPath'>;
-/** @deprecated */
+/**
+ * @deprecated This type was used for Apple's `altool`, which was sunset in 2023 and no longer works.
+ * @category Legacy
+ */
 export type NotarizeOptionsLegacy = {
     tool: 'legacy';
 } & LegacyNotarizeStartOptions;
+/**
+ * Options for notarizing your Electron app with `notarytool`.
+ * @category Core
+ */
+export type NotaryToolStartOptions = NotaryToolNotarizeAppOptions & NotaryToolCredentials;
+/**
+ * Helper type that specifies that `@electron/notarize` is using the `notarytool` strategy.
+ * @category Utility Types
+ */
 export type NotarizeOptionsNotaryTool = {
     tool?: 'notarytool';
 } & NotaryToolStartOptions;
+/**
+ * Options accepted by the `notarize` method.
+ * @internal
+ */
 export type NotarizeOptions = NotarizeOptionsLegacy | NotarizeOptionsNotaryTool;
+export {};

lib/validate-args.d.ts

@@ -11,2 +11,5 @@ import { LegacyNotarizeApiKeyCredentials, LegacyNotarizeCredentials, LegacyNotarizePasswordCredentials, NotaryToolApiKeyCredentials, NotaryToolCredentials, NotaryToolKeychainCredentials, NotaryToolPasswordCredentials } from './types';
 export declare function isNotaryToolKeychainCredentials(opts: NotaryToolCredentials): opts is NotaryToolKeychainCredentials;
+/**
+ * @internal
+ */
 export declare function validateNotaryToolAuthorizationArgs(opts: NotaryToolCredentials): NotaryToolCredentials;

lib/validate-args.js

@@ -63,2 +63,5 @@ "use strict";
 exports.isNotaryToolKeychainCredentials = isNotaryToolKeychainCredentials;
+/**
+ * @internal
+ */
 function validateNotaryToolAuthorizationArgs(opts) {
@@ -65,0 +68,0 @@ const isPassword = isNotaryToolPasswordCredentials(opts);

package.json

 {
   "name": "@electron/notarize",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Notarize your Electron app",
@@ -38,3 +38,5 @@ "main": "lib/index.js",
     "ts-jest": "^29.0.0",
-    "typescript": "^4.8.4"
+    "typedoc": "~0.25.13",
+    "typedoc-plugin-missing-exports": "^2.2.0",
+    "typescript": "4.9.3"
   },
@@ -41,0 +43,0 @@ "dependencies": {

README.md

@@ -12,7 +12,3 @@ Electron Notarize
 ```bash
-# npm
 npm install @electron/notarize --save-dev
-
-# yarn
-yarn add @electron/notarize --dev
 ```
@@ -24,7 +20,12 @@
 
-> 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.
+> 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.
+> 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).
+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.
 
@@ -36,78 +37,149 @@ ## Prerequisites
 1. Xcode 13 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`
+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.
 
-  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.
+> [!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.
 
 ## API
 
-### Method: `notarize(opts): Promise<void>`
+`@electron/notarize` exposes a single `notarize` function that accepts the following parameters:
+* `appPath` — the absolute path to your codesigned and packaged Electron application.
+* additional options required for authenticating your Apple ID (see below)
 
-* `options` Object
-  * `tool` String - The notarization tool to use, default is `notarytool`.  Previously, the value `legacy` used `altool`, which [**stopped working** on November 1st 2023](https://developer.apple.com/news/?id=y5mjxqmn).
-  * `appPath` String - The absolute path to your `.app` file
-  * 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](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/) you want to notarize under.
-    * ... or apiKey with apiIssuer:
-      * `appleApiKey` String - Absolute path to the `.p8` file containing the key. Required for JWT authentication. See Note on JWT authentication below.
-      * `appleApiKeyId` String - App Store Connect API key ID, for example, `T9GPZ92M7K`. Required for JWT authentication. See Note on JWT authentication below.
-      * `appleApiIssuer` String - Your App Store Connect API key issuer, for example, `c055ca8c-e5a8-4836-b61d-aa5794eeb3f4`. Required if `appleApiKey` is specified.
-    * ... or keychain with keychainProfile:
-      * `keychain` String (optional) - The name of the keychain or path to the keychain you stored notarization credentials in. If omitted, iCloud keychain is used by default.
-      * `keychainProfile` String - The name of the profile you provided when storing notarization credentials.
+The method returns a void Promise once app notarization is complete. Please note that notarization may take
+many minutes.
 
-## Safety when using `appleIdPassword`
+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).
 
-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:
+### 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
-const password = `@keychain:"Application Loader: ${appleId}"`;
+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
+});
 ```
 
-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:
+> [!IMPORTANT]
+> **Never hard code your app-specific password into your packaging scripts.** Use an environment
+> variable at a minimum.
 
-```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:
+### 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
-const password = `@keychain:AC_PASSWORD`;
+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`)
+});
 ```
 
-## Notes on JWT authentication
+### Usage with Keychain credentials
 
-You can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/api). Create a _Team Key_ (not an _Individual 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_<appleApiKeyId>.p8`. Provide the path to this file as the `appleApiKey` argument.
+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.
 
-## Notes on your teamId
+This method has the advantage of validating your notarization credentials before submitting
+your application for notarization.
 
-To get your `teamId` value, go to your [Apple Developer Account](https://developer.apple.com/account), then click on "Membership details", and there you will find your Team ID.
+For example:
 
-## Debug
+```sh
+# App-specific password strategy
+xcrun notarytool store-credentials "my-app-password-profile"
+  --apple-id "<AppleID>"
+  --team-id <DeveloperTeamID>
+  --password <app_specific_password>
+```
 
-[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages. You can use `export DEBUG=electron-notarize*` to log additional debug information from this module.
+```sh
+# App Store Connect API key strategy
+xcrun notarytool store-credentials "my-api-key-profile"
+  --key "<PathToAPIKey>"
+  --key-id <KeyID>
+  --issuer <IssuerID>
+```
 
-## Example Usage
+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';
 
-async function packageTask () {
-  // Package your app here, and code sign with hardened runtime
-  await notarize({
-    appPath,
-    appleId,
-    appleIdPassword,
-    teamId,
-  });
-}
+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).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

60498

increased by11.44%

Lines of code

848

increased by18.27%

Number of lines in readme file

183

increased by64.86%

Worsened metrics

Dev dependency count

11

increased by22.22%

No dependency changes