Making notarization work on macOS for Electron apps built with Electron Builder

A pen on a piece of paper

Learn how to set up notarization on macOS for Electron apps built with Electron Builder and work around a bizarre issue I’ve experienced with Apple Notarization Service.

I ❤️ building things and, when it comes to software, I’ve done that for quite a few platforms and in various programming languages over the years. Recently I’ve been developing a desktop app built with Electron and I must say the whole first-timer experience has been rather pleasing. One thing that required “a bit” of attention was the build process for different platforms (Windows, macOS) and part of it was the app notarization step on macOS. What on paper looked like a really easy thing to do, took me a couple of hours and a lot of detective work to get it right 🕵️‍♀️.

Below is a step by step guide on how to set up notarization on macOS when using Electron Builder (22.7.0) and Electron Notarize (1.0.0), including a complete workaround for an issue I’ve experienced that has to do with Apple Notarization Service. Hopefully, I will be able to help you out like a true superhero 🦸🏻‍♂️, so your time and effort can be devoted to other, more pressing matters 🦾.

A bit of context

Want the solution right away 🧐? Skip to the step by step guide.

Why even bother with notarization in the first place? Well, on macOS (and Windows for that matter) there are various security mechanisms built into the operating system to prevent malicious software from being installed and run on a machine. macOS and Windows both require installers and binaries to be cryptographically signed with a valid certificate. On macOS, however, there is an additional build-time notarization step that involves sending a compressed .app archive to Apple’s Notarization Service (ANS) for verification.

In most instances, the whole process is painless, but in my case, i.e. an Electron app with a lot of dependencies and third-party binaries, not so much 🤕. For some reason ANS was rejecting my application archives uploaded by Electron Notarize with The signature of the binary is invalid reason.

Update #1 (15.09.2021)

I’ve learned about the real cause of the issue some time after writing this article. In the original text, I’ve stopped investigating after coming up with a quick monkey patch to Electron Notarize. You can learn why in a follow up essay. Hope you love it!

My first guess was that there’s something wrong with the way the archive is created, so I’ve created two .app archives using:

  1. Command-line zip utility,
  2. “Compress” option found in Finder,

And submitted them for notarization from the command line. The Finder-created archive passed, while zip-one failed.

The zipinfo command line tool reveals that:

  • Finder uses PKZIP 2.0 scheme, while zip version 3.0 of the generic ZIP algorithm.
  • Finder compresses all the files in .app as binaries, while “zip” treats files according to the content type (code as text, binaries as binaries).
  • Finder includes magical __MACOSX folders to embed macOS-specific attributes into the archive, especially for links to dynamic libraries (e.g. found in some Node modules).

However, it turns out the above differences are only part of the story. As pointed out by Skywalker13 on GitHub, macOS’s zip utility converts UTF-8 NFD charset to UTF-8 NFC. The new APFS filesystem supports both encodings, unlike HFS+, where UTF-8 is always converted to UTF-8 NFD. In other words, some filenames will be different in .app and the zipped archive, causing signature mismatches.

Update #2 (15.09.2021)

As of version 1.0.1, Electron Notarize uses ditto by default, so there’s no need for the monkey-patching described below.

One way of getting around the above issue is to use ditto instead of zip to create a compressed archive of an .app package. Ditto is a command line tool shipped with macOS for copying directories and creating/extracting archives. It uses the same scheme as Finder (PKZIP) and preserves metadata, thus making the output compatible with Apple’s service. The relevant options for executing ditto in this context, i.e. to mimic Finder’s behavior, are:

  • -c and -k to create a PKZIP-compressed archive,
  • —sequesterRsrc to preserve metadata (__MACOSX),
  • —keepParent to embed parent directory name source in the archive.

The complete invocation looks as follows:

ditto -c -k —sequesterRsrc —keepParent APP_NAME.app APP_NAME.app.zip

To apply this to Electron Builder’s notarization flow, you need to monkey patch Electron Notarize’s .app and make the compress step use ditto. This can be done via “afterSign” hook defined in the Electron Builder’s configuration file.

Setting up macOS app notarization, including workaround

Before you start, you first need to properly configure code signing, as per the official documentation of Electron Builder and various guides1. For completeness sake I’ve included here all the steps required for making the notarization to work based on my experience and an excellent work by other developers1.

1. Create an app-specific password to use with Apple notarization service. Preferably using your organization’s developer Apple ID.

2. Create an Entitlements .plist file specific to your Electron apps. In our case, the following did the trick:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <!-- https://github.com/electron/electron-notarize#prerequisites -->
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
    <true/>
    <!-- https://github.com/electron-userland/electron-builder/issues/3940 -->
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
  </dict>
</plist>

3. Set entitlements and entitlementInherit options for macOS build in Electron Builder’s configuration file to the .plist created in the previous step.

4. Create a notarize.js script to execute after Electron Builder signs the .app and its contents. Place the file in the build directory defined in Electron Builder’s configuration file.

const {notarize} = require("electron-notarize");

exports.default = async function notarizing(context) {
  const {electronPlatformName, appOutDir} = context;

  if (electronPlatformName !== "darwin") {
    return;
  }

  const appName = context.packager.appInfo.productFilename;

  return await notarize({
    appBundleId: process.env.APP_BUNDLE_ID,
    appPath: `${appOutDir}/${appName}.app`,
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_ID_PASSWORD,
  });
};

5. Add "afterSign": "./PATH_TO_NOTARIZE_JS_IN_BUILD_DIRECTORY” to Electron Builder’s configuration file.

6. Monkey patch Electron Notarize. The script should run before Electron Builder’s CLI command. In our case, since we’ve taken a very modular approach to general app architecture, the build scripts (TypeScript files) include a separate commons module, which is imported by Electron Notarize patcher. The .ts files can be executed using ts-node via

ts-node -O {\"module\":\"CommonJS\"} scripts/patch-electron-notarize.ts

The patcher itself does one thing only, that is, it replaces the following piece of the code in build/node_modules/electron-notarize/lib/index.js:

spawn('zip', ['-r', '-y', zipPath, path.basename(opts.appPath)]

with

spawn('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', path.basename(opts.appPath), zipPath]

Our code for the commons:

import {promises as fsp} from "fs";

export type FileContentsTransformer = (content: string) => string;

export async function replaceFileContents(path: string, transformer: FileContentsTransformer) {
  let fh: fsp.FileHandle | null = null;
  let content: string = "";

  try {
    fh = await fsp.open(path, "r");

    if (fh) {
      content = (await fh.readFile()).toString();
    }
  } finally {
    if (fh) {
      await fh.close();
    }
  }

  try {
    fh = await fsp.open(path, "w");

    if (fh) {
      await fh.writeFile(transformer(content));
    }
  } finally {
    if (fh) {
      await fh.close();
    }
  }
}

and the patcher:

import {FileContentsTransformer, replaceFileContents} from "./common";

const ELECTRON_NOTARIZE_INDEX_PATH = "build/node_modules/electron-notarize/lib/index.js";

async function main() {
  const transformer: FileContentsTransformer = (content: string) => {
    return content.replace(
        "spawn('zip', ['-r', '-y', zipPath, path.basename(opts.appPath)]",
        "spawn('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', path.basename(opts.appPath), zipPath]"
    );
  };

  await replaceFileContents(ELECTRON_NOTARIZE_INDEX_PATH, transformer);
}

// noinspection JSIgnoredPromiseFromCall
main();

7. Set APPLE_ID and APPLE_ID_PASSWORD environment variables (the ones defined in Step 1) before running Electron Builder on your developer machine or in your CI environment. You can use Keychain on your local machine instead.

And that’s pretty much it. You can check out a simple, working example to see how to put this all together. Now you can spend the extra time on something you enjoy doing 🏖!

Three takeaways

1. When stuck, look for the root cause in the least expected places. In the case of my project, the compression step was the unexpected culprit.

2. Be stubborn when a particular feature or bugfix is essential to a product’s success. Here, the notarization was important and it took some time to get it right, but the end result is customers feeling safe when installing the software.

3. Sometimes “working” is good enough. I could develop a better solution, but that would take some precious time. I opted to focus on more pressing issues instead.

Feedback and questions are more than welcome, either in comments or on social media 🙂

Thanks a ton to Piotr Tomiak (@PiotrTomiak) and Jakub Tomanik (@jakub_tomanik) for reading drafts of this article.

1 Relevant sources:

2 GitHub Gists of the complete code