@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 the most basic tools and assets. Note that the bare necessities here are sufficient for enabling app sandbox, yet other configurations for network access etc. require additional work.
NB: Since @electron/osx-sign injects the entry com.apple.security.application-groups into the entitlements file as part of the pre-signing process, this would reportedly limit app transfer on iTunes Connect (see #150). However, opting out entitlements automation opts['preAutoEntitlements'] === false may result in worse graphics performance.
The signing procedure implemented in this package is based on what described in Code Signing Guide.
# For use in npm scripts
npm install --save @electron/osx-sign
# yarn
yarn add @electron/osx-sign
# For use from CLI
npm install -g @electron/osx-sign
# Yarn
yarn global add @electron/osx-sign
Note: @electron/osx-sign is a dependency of electron-packager as of 6.0.0 for signing apps on macOS. However, feel free to install this package globally for more customization beyond specifying identity and entitlements.
const { signAsync } = require('@electron/osx-sign')
signAsync({
app: 'path/to/my.app'
})
.then(function () {
// Application signed
})
.catch(function (err) {
// Handle the error
})
Required
app - String
Path to the application package.
Needs file extension .app.
Optional
binaries - Array
Path to additional binaries that will be signed along with built-ins of Electron.
Default to undefined.
optionsForFile - Function
Function that receives the path to a file and can return the entitlements to use for that file to override the default behavior. The object this function returns can include any of the following optional keys.
| Option | Description | Usage Example |
|---|---|---|
entitlements | String specifying the path to an entitlements.plist file. Will default to built-in entitlements files. Can also be an array of entitlement keys that osx-sign will write to an entitlements file for you. | 'path/to/entitlements' |
hardenedRuntime | Boolean flag to enable the Hardened Runtime when signing the app. Enabled by default. | false |
requirements | String specifying the requirements that you recommend to be used to evaluate the code signature. | 'anchor apple or anchor = "/var/db/yourcorporateanchor.cert"' |
signatureFlags | List of code signature flags. Accepts an array of strings or a comma-separated string. | ['kSecCodeSignatureRestrict'] |
timestamp | String specifying the URL of the timestamp authority server. Defaults to the server provided by Apple. Please note that this default server may not support signatures not furnished by Apple. Disable the timestamp service with none. | 'https://different.timeserver' |
Note: Only available via the JS API
identity - String
Name of certificate to use when signing.
Default to be selected with respect to provisioning-profile and platform from keychain or keychain by system default.
Signing platform mas will look for 3rd Party Mac Developer Application: * (*), and platform darwin will look for Developer ID Application: * (*) by default.
identityValidation - Boolean
Flag to enable/disable validation for the signing identity. If enabled, the identity provided will be validated in the keychain specified.
Default to true.
keychain - String
The keychain name. Default to system default keychain.
ignore - RegExp|Function|Array.<(RegExp|Function)>
Regex, function or an array of regex's and functions that signal skipping signing a file.
Elements of other types are treated as RegExp.
Default to undefined.
platform - String
Build platform of Electron.
Allowed values: darwin, mas.
Default to auto detect by presence of Squirrel.framework within the application bundle.
preAutoEntitlements - Boolean
Flag to enable/disable automation of com.apple.security.application-groups in entitlements file and update Info.plist with ElectronTeamID.
Default to true.
preEmbedProvisioningProfile - Boolean
Flag to enable/disable embedding of provisioning profile in the current working directory.
Default to true.
provisioningProfile - String
Path to provisioning profile.
strictVerify - Boolean|String|Array.
Flag to enable/disable --strict flag when verifying the signed application bundle.
If provided as a string, each component should be separated with comma (,).
If provided as an array, each item should be a string corresponding to a component.
Default to true.
type - String
Specify whether to sign app for development or for distribution.
Allowed values: development, distribution.
Default to distribution.
version - String
Build version of Electron.
Values may be like: 1.1.1, 1.2.0.
Default to latest Electron version.
It is recommended to utilize this option for best support of specific Electron versions. This may trigger pre/post operations for signing: For example, automation of setting com.apple.security.application-groups in entitlements file and of updating Info.plist with ElectronTeamID is enabled for all versions starting from 1.1.1; set preAutoEntitlements option to false to disable this feature.
electron-osx-sign app [embedded-binary ...] [options ...]
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 --pre-auto-entitlements) distribution builds can no longer be run directly. To run the 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 provide the flag --no-pre-auto-entitlements 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).
The examples below assume that --pre-auto-entitlements is enabled.
To sign a distribution version by default:
electron-osx-sign path/to/my.app
For distribution in the Mac App Store: Have 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 iTunes Connect. For distribution outside the Mac App Store: Have the signing identity for distribution installed in the default keychain and optionally place the provisioning profile in the current working directory. By default App Sandbox is not enabled. The app should run on all devices.
To sign development version:
electron-osx-sign path/to/my.app --type=development
For testing Mac App Store builds: Have the provisioning profile for development placed in the current working directory and the signing identity installed in the default keychain. The app will only run on provisioned devices. For testing apps for distribution outside the Mac App Store, have the signing identity for development installed in the default keychain and optionally the provisioning profile placed in the current working directory. The app will only run on provisioned devices. However, you may prefer to just go with signing a distribution version because the app is expected to launch properly after codesigned.
It is recommended to place the provisioning profile(s) under the working directory for electron-osx-sign to pick up automatically; however, to specify provisioning profile to be embedded explicitly:
electron-osx-sign path/to/my.app --provisioning-profile=path/to/my.provisionprofile
To specify custom entitlements files you have to use the JS API.
It is recommended to make use of --version while signing legacy versions of Electron:
electron-osx-sign path/to/my.app --version=0.34.0
Run electron-osx-sign --help or see electron-osx-sign-usage.txt for CLI-specific options.
const { flatAsync } = require('@electron/osx-sign')
flatAsync({
app: 'path/to/my.app'
})
.then(function () {
// Application flattened
})
.catch(function (err) {
// Handle the error
})
Required
app - String
Path to the application bundle.
Needs file extension .app.
Optional
identity - String
Name of certificate to use when signing.
Default to be selected with respect to platform from keychain or keychain by system default.
Flattening platform mas will look for 3rd Party Mac Developer Installer: * (*), and platform darwin will look for Developer ID Installer: * (*) by default.
identityValidation - Boolean
Flag to enable/disable validation for signing identity. If enabled, the identity provided will be validated in the keychain specified.
Default to true.
install - String
Path to install the bundle.
Default to /Applications.
keychain - String
The keychain name. Default to system default keychain.
platform - String
Build platform of Electron. Allowed values: darwin, mas.
Default to auto detect by presence of Squirrel.framework within the application bundle.
pkg - String
Path to the output the flattened package.
Needs file extension .pkg.
scripts - String
Path to a directory containing pre and/or post install scripts.
electron-osx-flat app [options ...]
Example:
electron-osx-flat path/to/my.app
Run electron-osx-flat --help or see electron-osx-flat-usage.txt for CLI-specific options.
As of release v0.3.1, external module debug is used to display logs and messages; remember to export DEBUG=electron-osx-sign* when necessary.
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-download 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-download 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 223,671 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
The 2023 Python Developers Survey reveals key trends in packaging, web frameworks, and developer demographics, highlighting a shift toward innovative tools as the Python community diversifies and grows among less experienced developers.
Security News
GitHub is combatting a new spam campaign that exploits issues with links to malicious downloads, highlighting the need for better moderation tools to protect open-source maintainers' time and security.
Security News
uv, Python's new package manager, offers a faster and more efficient alternative to pip with features that simplify tooling, manage Python versions, and streamline development workflows.