{"id":13509592,"url":"https://github.com/electron/notarize","last_synced_at":"2025-05-14T14:06:04.003Z","repository":{"id":33716378,"uuid":"154179487","full_name":"electron/notarize","owner":"electron","description":"Notarize your macOS Electron Apps","archived":false,"fork":false,"pushed_at":"2025-05-01T12:25:46.000Z","size":447,"stargazers_count":163,"open_issues_count":14,"forks_count":34,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-07T22:30:06.382Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-10-22T16:42:16.000Z","updated_at":"2025-05-02T17:51:31.000Z","dependencies_parsed_at":"2023-02-18T19:45:49.184Z","dependency_job_id":"2c8ee247-d083-424a-883f-1fb3419c83bd","html_url":"https://github.com/electron/notarize","commit_stats":{"total_commits":122,"total_committers":35,"mean_commits":"3.4857142857142858","dds":0.7213114754098361,"last_synced_commit":"669f1c2515384270f0121cde4e7fae23d69de9b7"},"previous_names":["electron/electron-notarize"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fnotarize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fnotarize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fnotarize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fnotarize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electron","download_url":"https://codeload.github.com/electron/notarize/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253632844,"owners_count":21939377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:01:10.049Z","updated_at":"2025-05-14T14:06:03.997Z","avatar_url":"https://github.com/electron.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"Electron Notarize\n-----------\n\n\u003e Notarize your Electron apps seamlessly for macOS\n\n[![Test](https://github.com/electron/notarize/actions/workflows/test.yml/badge.svg)](https://github.com/electron/notarize/actions/workflows/test.yml)\n[![NPM package](https://img.shields.io/npm/v/@electron/notarize)](https://npm.im/@electron/notarize)\n\n## Installation\n\n```bash\nnpm install @electron/notarize --save-dev\n```\n\n## What is app \"notarization\"?\n\nFrom Apple's docs in XCode:\n\n\u003e A notarized app is a macOS app that was uploaded to Apple for processing before it was distributed.\n\u003e When you export a notarized app from Xcode, it code signs the app with a Developer ID certificate\n\u003e and staples a ticket from Apple to the app. The ticket confirms that you previously uploaded the app to Apple.\n\n\u003e On macOS 10.14 and later, the user can launch notarized apps when Gatekeeper is enabled.\n\u003e When the user first launches a notarized app, Gatekeeper looks for the app’s ticket online.\n\u003e If the user is offline, Gatekeeper looks for the ticket that was stapled to the app.\n\nAs macOS 10.15 (Catalina), Apple has made notarization a hard requirement for all applications\ndistributed outside of the Mac App Store. App Store applications do not need to be notarized.\n\n## Prerequisites\n\nFor notarization, you need the following things:\n\n1. Xcode 13 or later installed on your Mac.\n1. An [Apple Developer](https://developer.apple.com/) account.\n1. [An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).\n1. Your app may need to be signed with `hardenedRuntime: true` option, with the `com.apple.security.cs.allow-jit` entitlement.\n\n\u003e [!NOTE]\n\u003e If you are using Electron 11 or below, you must add the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement too.\n\u003e When using version 12+, this entitlement should not be applied as it increases your app's attack surface.\n\n\n## API\n\n`@electron/notarize` exposes a single `notarize` function that accepts the following parameters:\n* `appPath` — the absolute path to your codesigned and packaged Electron application.\n* `notarytoolPath` - String (optional) - Path to a custom notarytool binary ([more details](#custom-notarytool)) \n* additional options required for authenticating your Apple ID (see below)\n\nThe method returns a void Promise once app notarization is complete. Please note that notarization may take\nmany minutes.\n\nIf the notarization process is unusually long for your application, see Apple Developer's docs to\n[Avoid long notarization response times and size limits](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow#3561440).\n\n### Usage with app-specific password\n\nYou can generate an [app-specific password](https://support.apple.com/en-us/102654) for your Apple ID\nto notarize your Electron applications.\n\nThis method also requires you to specify the [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)\nof the Developer Team you want to notarize under. An Apple ID may be part of multiple Teams.\n\n```javascript\nimport { notarize } from '@electron/notarize';\n\nawait notarize({\n  appPath,\n  appleId, // Login name of your Apple Developer account\n  appleIdPassword, // App-specific password\n  teamId, // Team ID for your developer team\n});\n```\n\n\u003e [!IMPORTANT]\n\u003e **Never hard code your app-specific password into your packaging scripts.** Use an environment\n\u003e variable at a minimum.\n\n### Usage with App Store Connect API key\n\nAlternatively, you can also authenticate via JSON Web Token (JWT) with App Store Connect.\n\nYou can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api).\nCreate a **Team Key** (not an _Individual Key_) with **App Manager** access.\n\nNote down the Issuer ID (UUID format) and Key ID (10-character alphanumeric string),\nand download the `.p8` API key file (`AuthKey_\u003cappleApiKeyId\u003e.p8`).\nFor security purposes, the private key can only be downloaded once.\n\nProvide the absolute path to your API key as the `appleApiKey` argument.\n\n```javascript\nimport { notarize } from '@electron/notarize';\n\nawait notarize({\n  appPath,\n  appleApiKey, // Absolute path to API key (e.g. `/path/to/AuthKey_X0X0X0X0X0.p8`)\n  appleApiIssuer, // Issuer ID (e.g. `d5631714-a680-4b4b-8156-b4ed624c0845`)\n});\n```\n\n### Usage with Keychain credentials\n\nAs an alternative to passing authentication options, you can also store your authentication\ncredentials (for both API key and app-specific password strategies) in the macOS Keychain\nvia the `xcrun notarytool` command-line utility.\n\nThis method has the advantage of validating your notarization credentials before submitting\nyour application for notarization.\n\nFor example:\n\n```sh\n# App-specific password strategy\nxcrun notarytool store-credentials \"my-app-password-profile\"\n  --apple-id \"\u003cAppleID\u003e\"\n  --team-id \u003cDeveloperTeamID\u003e\n  --password \u003capp_specific_password\u003e\n```\n\n```sh\n# App Store Connect API key strategy\nxcrun notarytool store-credentials \"my-api-key-profile\"\n  --key \"\u003cPathToAPIKey\u003e\"\n  --key-id \u003cKeyID\u003e\n  --issuer \u003cIssuerID\u003e\n```\n\nSuccessful storage of your credentials will look like this:\n\n```\nThis process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.\n\nValidating your credentials...\nSuccess. Credentials validated.\nCredentials saved to Keychain.\nTo use them, specify `--keychain-profile \"my-api-key-profile\"`\n```\n\nAfter successfully storing your credentials, pass the keychain profile name into\nthe `keychainProfile` parameter.\n\n```javascript\nimport { notarize } from '@electron/notarize';\n\nawait notarize({\n  appPath,\n  keychainProfile,\n});\n```\n\n### Custom notarytool\n\nYou can provide a path to a custom `notarytool`. This module allows this option to enable unique edge cases - but this use case is _explicitly unsupported_. \n\n## Troubleshooting\n\n### Debug logging\n\n[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages.\nRun your notarization scripts with the `DEBUG=electron-notarize*` environment variable to log additional\ndebug information from this module.\n\n### Validating credentials\n\nWhen notarizing your application, you may run into issues with validating your notarization\ncredentials.\n\n```\nError: HTTP status code: 401. Invalid credentials. Username or password is incorrect.\nUse the app-specific password generated at appleid.apple.com. Ensure that all authentication arguments are correct.\n```\n\n[Storing your credentials in Keychain](#usage-with-keychain-credentials) will validate your credentials before\neven GitHub.\n\n### Validating app notarization\n\nTo validate that notarization worked, you can use the `stapler` command-line utility:\n\n```sh\nstapler validate path/to/notarized.app\n```\n\n### Apple documentation\n\nApple also provides additional debugging documentation on\n[Resolving common notarization issues](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron%2Fnotarize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectron%2Fnotarize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron%2Fnotarize/lists"}