node-mac-permissions

The node-mac-permissions module provides a native interface to manage and request access to various macOS privacy and security permissions, including:

• Apple Events
• Accessibility
• Calendar
• Camera
• Contacts
• External Storage Devices
• Focus Status
• Full Disk Access
• Input Monitoring
• Location
• Microphone
• Photos
• Protected Folders
• Reminders
• Screen Capture
• Speech Recognition
• Notifications

Install the module using npm to manage macOS app permissions from a Node.js environment.

npm i node-mac-permissions

To successfully trigger permission prompts, your environment must meet specific requirements depending on how you are running your code:

Node.js Scripts/Apps

Standard macOS Terminal.app does not support permission prompts for scripts. You must use a terminal emulator like iTerm2 to allow the app to request permissions.

Electron Apps

For Electron or similar bundled applications, you must update your Info.plist to include usage description keys. For example, to request microphone access, you must include NSMicrophoneUsageDescription.

macOS 12.3+ Requirement

If you are running on macOS 12.3 or newer, ensure that Python is installed on your system, as it is no longer bundled by default with macOS.

If you encounter a TypeError: Cannot read property 'indexOf' of undefined at bindings.js while using webpack, it indicates that webpack is attempting to pack this module. node-mac-permissions should not be packed by webpack. To resolve this, configure webpack to treat this module as an external dependency (e.g., using the externals configuration) so it is not included in the bundle.

App threw an error during load
TypeError: Cannot read property 'indexOf' of undefined
    at Function.getFileName (webpack-internal:///./node_modules/bindings/bindings.js:178:16)

Use askForScreenCaptureAccess([openPreferences]) to request permission for screen recording.

• openPreferences: (Optional) Boolean. If true, opens System Preferences if the request is denied or fails.

Behavior:

• Calling this for the first time in a session triggers a permission modal.
• If the modal is denied, there is no programmatic way to request it again, unless openPreferences is set to true, which will open the Screen Capture pane in Security & Privacy.

const { askForScreenCaptureAccess } = require('node-mac-permissions')

askForScreenCaptureAccess()

Use askForAppleEventsAccess(targetAppBundleId[, shouldPrompt]) to request permission to send Apple Events to a specific application.

• targetAppBundleId: The bundle identifier of the target app (e.g., com.apple.finder).
• shouldPrompt: (Optional) Boolean. If false, returns the current status without prompting. Defaults to true.

Returns: Promise<String> resolving to authorized, denied, or not determined.

Requirement: You must add the NSAppleEventsUsageDescription key to your app's Info.plist.

const { askForAppleEventsAccess } = require('node-mac-permissions')

askForAppleEventsAccess('com.apple.finder').then(status => {
  console.log(`Access to send Apple Events is ${status}`)
})

There is no programmatic API to request Accessibility access on macOS. Calling askForAccessibilityAccess() will trigger the opening of the Accessibility pane within the Security & Privacy section of System Preferences.

const { askForAccessibilityAccess } = require('node-mac-permissions')

askForAccessibilityAccess()

Use askForExternalStorageAccess() to request permission for capturing onto external storage devices. This requires macOS 14.0 or higher.

Returns: Promise<String> resolving to authorized, denied, or not determined.

Behavior:

• If not determined: Prompts the user. Resolves to authorized or denied.
• If denied: Resolves to denied.
• On older macOS versions: Resolves to not determined.

const { askForExternalStorageAccess } = require('node-mac-permissions')

askForExternalStorageAccess().then(status => {
  console.log(`Access to External Storage is ${status}`)
})

There is no programmatic API to request Full Disk Access. Calling askForFullDiskAccess() will trigger the opening of the Full Disk Access pane within Security & Privacy.

Requirement: To trigger a system dialog when attempting to access protected resources, add the NSSystemAdministrationUsageDescription key to your Info.plist.

const { askForFullDiskAccess } = require('node-mac-permissions')

askForFullDiskAccess()

Use askForContactsAccess() to request access to the user's Contacts.

Returns: Promise<String> resolving to authorized or denied.

Requirement: You must add the NSContactsUsageDescription key to your app's Info.plist.

const { askForContactsAccess } = require('node-mac-permissions')

askForContactsAccess().then(status => {
  console.log(`Access to Contacts is ${status}`)
})

Use askForSpeechRecognitionAccess() to request permission for speech recognition.

Returns: Promise<String> resolving to authorized, denied, or restricted.

Behavior:

• If not determined: Prompts the user. Resolves to authorized or denied.
• If denied: Opens Security & Privacy with the Speech Recognition key highlighted. Resolves to denied.
• If restricted: Resolves to restricted.

Requirement: You must add the NSSpeechRecognitionUsageDescription key to your Info.plist.

const { askForSpeechRecognitionAccess } = require('node-mac-permissions')

askForSpeechRecognitionAccess().then(status => {
  console.log(`Access to Speech Recognition is ${status}`)
})