@electron/osx-sign
Advanced tools
@electron/osx-sign is an npm package designed to help developers sign and verify macOS applications built with Electron. This is crucial for distributing macOS applications outside the Mac App Store, as it ensures the app is trusted by the operating system and users.
Code Signing
This feature allows you to sign your Electron application with a specified identity. Code signing is essential for macOS applications to be recognized as trusted software.
const sign = require('@electron/osx-sign').sign;
sign({
app: 'path/to/your/app',
identity: 'Developer ID Application: Your Name (XXXXXXXXXX)'
}, function done (err) {
if (err) {
console.error('Error during signing:', err);
} else {
console.log('Application signed successfully');
}
});Verification
This feature allows you to verify that your Electron application has been signed correctly. Verification ensures that the app's signature is valid and has not been tampered with.
const verify = require('@electron/osx-sign').verify;
verify({
app: 'path/to/your/app'
}, function done (err, result) {
if (err) {
console.error('Error during verification:', err);
} else {
console.log('Verification result:', result);
}
});Notarization
This feature allows you to notarize your Electron application with Apple. Notarization is a process that scans your app for malicious content and generates a ticket that allows macOS to recognize the app as safe.
const notarize = require('@electron/osx-sign').notarize;
notarize({
appBundleId: 'com.your.app',
appPath: 'path/to/your/app',
appleId: 'your-apple-id',
appleIdPassword: 'your-apple-id-password'
}, function done (err) {
if (err) {
console.error('Error during notarization:', err);
} else {
console.log('Application notarized successfully');
}
});electron-builder is a complete solution to package and build a ready-for-distribution Electron app for macOS, Windows, and Linux. It includes features for code signing and notarization, similar to @electron/osx-sign, but also provides additional functionalities for building and packaging the app.
electron-packager is a command-line tool and Node.js library that bundles Electron-based application source code with a renamed Electron executable and supporting files into folders ready for distribution. While it does not directly handle code signing or notarization, it can be used in conjunction with other tools like @electron/osx-sign to achieve similar results.
electron-forge is a complete tool for creating, publishing, and installing modern Electron applications. It provides a seamless experience for building and packaging Electron apps, and it integrates with other tools for code signing and notarization, offering a more comprehensive solution compared to @electron/osx-sign.
Codesign Electron macOS apps
@electron/osx-sign minimizes the extra work needed to eventually prepare
your apps for shipping, providing options that work out of the box for most applications.
Additional configuration is available via its API.
There are two main functionalities exposed via this package:
sign functions. Under the hood, this uses the codesign utility..pkg installer packages via flat functions. Under the hood, this uses the productbuild utility.@electron/osx-sign is integrated into other Electron packaging tools, and can be configured accordingly:
You can also install @electron/osx-sign separately if your packaging pipeline does not involve those tools:
npm install --save-dev @electron/osx-sign
The signing procedure implemented in this package is based on what described in Electron's Code Signing Guide.
xcode-select --install and follow the instructions.In order to distribute your application either inside or outside the Mac App Store, you will have to have the following certificates from Apple after becoming a registered developer.
Certificates can be created through the Certificates, Identities & Profiles page in the Apple Developer website or via Account Preferences in Xcode.
For distribution inside the Mac App Store, you will need to create:
3rd Party Mac Developer Application: * (*)3rd Party Mac Developer Installer: * (*)For distribution outside the Mac App Store:
Developer ID Application: * (*)Developer ID Installer: * (*)After you create the necessary certifications, download them and open each so that they are
installed in your keychain. We recommend installing them in your system default keychain so
that @electron/osx-sign can detect them automatically.
Note: They appear to come in pairs. It is preferred to have every one of them installed so not to are about which is not yet installed for future works. However, if you may only want to distribute outside the Mac App Store, there is no need to have the 3rd Party Mac Developer ones installed and vice versa.
const { signAsync } = require('@electron/osx-sign')
const opts = {
app: 'path/to/my.app'
};
signAsync(opts)
.then(function () {
// Application signed
})
.catch(function (err) {
// Handle the error
})
The only mandatory option for signAsync is a path to your .app package.
Configuration for most Electron apps should work out of the box.
For full configuration options, see the [API documentation].
const { signAsync } = require('@electron/osx-sign')
const opts = {
app: 'path/to/my.app',
// optional parameters for additional customization
platform: "mas", // should be auto-detected if your app was packaged for MAS via Packager or Forge
type: "distribution", // defaults to "distribution" for submission to App Store Connect
provisioningProfile: 'path/to/my.provisionprofile', // defaults to the current working directory
keychain: 'my-keychain', // defaults to the system default login keychain
};
signAsync(opts)
.then(function () {
// Application signed
})
.catch(function (err) {
// Handle the error
})
Mac App Store apps require a Provisioning Profile for submission to App Store Connect. We recommend having the provisioning profile for distribution placed in the current working directory and the signing identity installed in the default keychain.
The app is not expected to run after codesigning since there is no provisioned device, and it is
intended only for submission to App Store Connect. Since @electron/osx-sign adds the entry
com.apple.developer.team-identifier to a temporary copy of the specified entitlements file
(with the default option preAutoEntitlements), distribution builds can no longer be run directly.
To run an app codesigned for distribution locally after codesigning, you may manually add
ElectronTeamID in your Info.plist and com.apple.security.application-groups in the
entitlements file, and set preAutoEntitlements: false for @electron/osx-sign to avoid
this extra bit. Note that "certain features are only allowed across apps whose team-identifier value match"
(Technical Note TN2415).
Alternatively, set the app's type to development to codesign a development version of your app,
which will allow it to be run on your development provisioned machine. Apps signed for development
will not be eligible for submission via App Store Connect.
--deepSome subresources that you may include in your Electron app may need to be signed with --deep.
This is not typically safe to apply to the entire Electron app and therefore should be applied to just your file.
signAsync({
app: 'path/to/my.app',
optionsForFile: (filePath) => {
// For our one specific file we can pass extra options to be merged
// with the default options
if (path.basename(filePath) === 'myStrangeFile.jar') {
return {
additionalArguments: ['--deep'],
};
}
// Just use the default options for everything else
return null;
},
});
@electron/osx-sign maintains backwards compatibility with older versions of Electron, but
generally assumes that you are on the latest stable version.
If you are running an older unsupported version of Electron, you should pass in the version
option as such:
signAsync({
app: 'path/to/my.app',
version: '0.34.0',
});
This module also handles the creation of flat installer packages (.pkg installers).
[!NOTE] Modern
.pkginstallers are also named "flat" packages for historical purposes. Prior to Mac OS X Leopard (10.5), installation packages were organized in hierarchical directories. OS X Leopard introduced a new flat package format that is used for modern.pkginstallers.
const { flatAsync } = require('@electron/osx-sign')
flatAsync({
app: 'path/to/my.app'
})
.then(function () {
// Application flattened
})
.catch(function (err) {
// Handle the error
})
The only mandatory option for flatAsync is a path to your .app package.
For full configuration options, see the [API documentation].
@electron/osx-sign also exposes a legacy command-line interface (CLI) for both signing
and installer generation. However, we recommend using the JavaScript API as it has a more
complete API surface (e.g. optionsForFile is only available via JS).
# install the package locally into devDependencies
npm install --save-dev @electron/osx-sign
# Sign a packaged .app bundle
npx electron-osx-sign path/to/my.app [options ...]
# Create a .pkg installer from a packaged .app bundle
npx electron-osx-flat path/to/my.app [options ...]
For full options, use the --help flag for either command.
The debug module is used to display advanced logs and messages.
If you are having problems with signing your app with @electron/osx-sign, run your signing scripts with
the DEBUG=electron-osx-sign* environment variable.
The project's configured to run automated tests on CircleCI.
If you wish to manually test the module, first comment out opts.identity in test/basic.js to enable
auto discovery. Then run the command npm test from the dev directory.
When this command is run for the first time: @electron/get will download macOS Electron releases defined
in test/config.json, and save to ~/.electron/, which might take up less than 1GB of disk space.
A successful testing should look something like:
$ npm test
> electron-osx-sign@0.4.17 pretest electron-osx-sign
> rimraf test/work
> electron-osx-sign@0.4.17 test electron-osx-sign
> standard && tape test
Calling @electron/get before running tests...
Running tests...
TAP version 13
# setup
# defaults-test:v7.0.0-beta.3-darwin-x64
ok 1 app signed
# defaults-test:v7.0.0-beta.3-mas-x64
ok 2 app signed
# defaults-test:v6.0.3-darwin-x64
ok 3 app signed
# defaults-test:v6.0.3-mas-x64
ok 4 app signed
# defaults-test:v5.0.10-darwin-x64
ok 5 app signed
# defaults-test:v5.0.10-mas-x64
ok 6 app signed
# defaults-test:v4.2.9-darwin-x64
ok 7 app signed
# defaults-test:v4.2.9-mas-x64
ok 8 app signed
# defaults-test:v3.1.2-darwin-x64
ok 9 app signed
# defaults-test:v3.1.2-mas-x64
ok 10 app signed
# teardown
1..10
# tests 10
# pass 10
# ok
FAQs
Codesign Electron macOS apps
The npm package @electron/osx-sign receives a total of 284,747 weekly downloads. As such, @electron/osx-sign popularity was classified as popular.
We found that @electron/osx-sign demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.