GitHub - codebytere/node-mac-permissions: A native node module to manage system permissions on macOS. (original) (raw)

MIT license PRs Welcome Actions Status

node-mac-permissions

Table of Contents

Overview

npm i node-mac-permissions

This native Node.js module allows you to manage an app's access to:

If you need to ask for permissions, your app must be allowed to ask for permission :

If you're using macOS 12.3 or newer, you'll need to ensure you have Python installed on your system, as macOS does not bundle it anymore.

API

permissions.getAuthStatus(type)

Returns String - Can be one of not determined, denied, authorized, limited, provisional, or restricted.

Checks the authorization status of the application to access type on macOS.

Return Value Descriptions:

Notes:

Example:

const types = [ 'accessibility', 'bluetooth', 'calendar', 'camera', 'contacts', 'full-disk-access', 'input-monitoring', 'location', 'microphone', 'music-library', 'notifications', 'photos-add-only', 'photos-read-write', 'reminders', 'speech-recognition', 'screen', ]

for (const type of types) { const status = getAuthStatus(type) console.log(Access to <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi></mrow><mi>i</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">{type} is </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.854em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">t</span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mord mathnormal">p</span><span class="mord mathnormal">e</span></span><span class="mord mathnormal">i</span><span class="mord mathnormal">s</span></span></span></span>{status}) }

permissions.askForAccessibilityAccess()

There is no API for programmatically requesting Accessibility access on macOS at this time, and so calling this method will trigger opening of System Preferences at the Accessibility pane of Security and Privacy.

Example:

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

askForAccessibilityAccess()

permissions.askForAppleEventsAccess(targetAppBundleId[, shouldPrompt])

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized, denied, or not determined.

Your app’s Info.plist file must provide a value for the NSAppleEventsUsageDescription key that explains to the user why your app is requesting the ability to send Apple Events.

NSAppleEventsUsageDescription Your reason for wanting the ability to send Apple Events

Example:

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

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

permissions.askForContactsAccess()

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized or denied.

Your app’s Info.plist file must provide a value for the NSContactsUsageDescription key that explains to the user why your app is requesting Contacts access.

NSContactsUsageDescription Your reason for wanting to access the Contact store

Example:

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

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

permissions.askForCalendarAccess([accessLevel])

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized or denied.

Example:

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

askForCalendarAccess().then(status => { console.log(Access to Calendar is ${status}) })

On macOS 14 and newer, your app’s Info.plist file must provide a value for either the NSCalendarsWriteOnlyAccessUsageDescription key or the NSCalendarsFullAccessUsageDescription key that explains to the user why your app is requesting Calendar access.

NSCalendarsWriteOnlyAccessUsageDescription Your reason for wanting write-only Calendar access

NSCalendarsFullAccessUsageDescription Your reason for wanting full Calendar access

permissions.askForSpeechRecognitionAccess()

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized, denied, or restricted.

Checks the authorization status for Speech Recognition access. If the status check returns:

Your app must provide an explanation for its use of Speech Recognition using the NSSpeechRecognitionUsageDescription Info.plist key;

NSSpeechRecognitionUsageDescription Your reason for wanting to access Speech Recognition

Example:

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

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

Note: status will be resolved back as authorized prior to macOS 10.15, as the underlying API was not introduced until that version.

permissions.askForRemindersAccess()

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized or denied.

Example:

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

askForRemindersAccess().then(status => { console.log(Access to Reminders is ${status}) })

On macOS 14 and newer, your app’s Info.plist file must provide a value for the NSRemindersFullAccessUsageDescription key that explains to the user why your app is requesting Reminders access.

NSRemindersFullAccessUsageDescription Your reason for wanting access to read and write Reminders data.

permissions.askForFoldersAccess(folder)

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized or denied.

Example:

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

askForFoldersAccess('desktop').then(status => { console.log(Access to Desktop is ${status}) })

NSDesktopFolderUsageDescription Your reason for wanting to access the Desktop folder

NSDocumentsFolderUsageDescription Your reason for wanting to access the Documents folder

NSDownloadsFolderUsageDescription Your reason for wanting to access the Downloads folder

permissions.askForFullDiskAccess()

There is no API for programmatically requesting Full Disk Access on macOS at this time, and so calling this method will trigger opening of System Preferences at the Full Disk pane of Security and Privacy.

Example:

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

askForFullDiskAccess()

If you would like your app to pop up a dialog requesting full disk access when your app attempts to access protected resources, you should add the NSSystemAdministrationUsageDescription key to your Info.plist:

NSSystemAdministrationUsageDescription Your reason for wanting Full Disk Access

permissions.askForCameraAccess()

Returns Promise<String> - Current permission status; can be authorized, denied, or restricted.

Checks the authorization status for camera access. If the status check returns:

Your app must provide an explanation for its use of capture devices using the NSCameraUsageDescription Info.plist key; Calling this method or attempting to start a capture session without a usage description raises an exception.

NSCameraUsageDescription Your reason for wanting to access the Camera

Note:

Example:

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

askForCameraAccess().then(status => { console.log(Access to Camera is ${status}) })

permissions.askForLocationAccess([accessLevel])

Returns void.

Checks the authorization status for input monitoring access. If the status check returns:

Your app must provide an explanation for its use of location using either the NSLocationUsageDescription Info.plist key; Calling this method or attempting to access location without a usage description raises an exception.

NSLocationUsageDescription Your reason for wanting to access the user's Location

permissions.askForInputMonitoringAccess([accessLevel])

Returns Promise<String> - Current permission status; can be authorized or denied.

Checks the authorization status for input monitoring access. If the status check returns:

Note:

Example:

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

askForInputMonitoringAccess().then(status => { console.log(Access to Input Monitoring is ${status}) })

permissions.askForMicrophoneAccess()

Returns Promise<String> - Current permission status; can be authorized, denied, or restricted.

Checks the authorization status for microphone access. If the status check returns:

Your app must provide an explanation for its use of capture devices using the NSMicrophoneUsageDescription Info.plist key; Calling this method or attempting to start a capture session without a usage description raises an exception.

NSMicrophoneUsageDescription Your reason for wanting to access the Microphone

Note:

Example:

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

askForMicrophoneAccess().then(status => { console.log(Access to Microphone is ${status}) })

permissions.askForMusicLibraryAccess()

Returns Promise<String> - Whether or not the request succeeded or failed; can be authorized, denied, or restricted.

Your app must provide an explanation for its use of the music library using the NSAppleMusicUsageDescription Info.plist key.

NSAppleMusicUsageDescription Your reason for wanting to access the user’s media library.

Note:

Example:

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

askForMusicLibraryAccess().then(status => { console.log(Access to Apple Music Library is ${status}) })

permissions.askForPhotosAccess([accessLevel])

Returns Promise<String> - Current permission status; can be authorized, denied, or restricted.

Checks the authorization status for Photos access. If the status check returns:

Your app must provide an explanation for its use of the photo library using either the NSPhotoLibraryUsageDescription or the NSPhotoLibraryAddUsageDescription Info.plist key.

For requesting add-only access to the user’s photo library:

NSPhotoLibraryAddUsageDescription Your reason for wanting to access Photos

For requesting read/write access to the user’s photo library:

NSPhotoLibraryUsageDescription Your reason for wanting to access Photos

Note:

You should add the PHPhotoLibraryPreventAutomaticLimitedAccessAlert key with a Boolean value of YES to your app’s Info.plist file to prevent the system from automatically presenting the limited library selection prompt. See PHAuthorizationStatusLimited for more information.

Example:

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

askForPhotosAccess().then(status => { console.log(Access to Photos is ${status}) })

permissions.askForScreenCaptureAccess([openPreferences])

Calling this method for the first time within an app session will trigger a permission modal. If this modal is denied, there is no API for programmatically requesting Screen Capture on macOS at this time. Calling this method after denial with openPreferences = true will trigger opening of System Preferences at the Screen Capture pane of Security and Privacy.

Example:

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

askForScreenCaptureAccess()

FAQ

Q. I'm seeing an error like the following when using webpack:

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)

A. This error means that webpack packed this module, which it should not. To fix this, you should configure webpack to use this module externally, e.g explicitly not pack it.

Q. I've authorized access to a particular system component and want to reset it. How do I do that?

A. You can use tccutil to do this!

The tccutil command manages the privacy database, which stores decisions the user has made about whether apps may access personal data.

Examples:

Reset all app permissions

$ tccutil reset All

Reset Accessibility access permissions

$ tccutil reset Accessibility

Reset Reminders access permissions

$ tccutil reset Reminders

Reset Calendar access permissions

$ tccutil reset Calendar

Reset Camera access permissions

$ tccutil reset Camera

Reset Microphone access permissions

$ tccutil reset Microphone

Reset Photos access permissions

$ tccutil reset Photos

Reset Screen Capture access permissions

$ tccutil reset ScreenCapture

Reset Full Disk Access permissions

$ tccutil reset SystemPolicyAllFiles

Reset Contacts permissions

$ tccutil reset AddressBook

Reset Desktop folder access

$ tccutil reset SystemPolicyDesktopFolder

Reset Documents folder access

$ tccutil reset SystemPolicyDocumentsFolder

Reset Downloads folder access

$ tccutil reset SystemPolicyDownloadsFolder

Reset Removable Volumes access

$ tccutil reset SystemPolicyRemovableVolumes