Merge pull request #1599 from freakboy3742/permissions

Add the ability to define app permissions

changes/547.feature.rst

@@ -0,0 +1 @@
+App permissions can now be declared as part of an app's configuration.

docs/reference/configuration.rst

@@ -458,6 +458,38 @@ sources from all levels, starting from least to most specific.
 
 A URL where more details about the application can be found.
 
+Permissions
+===========
+
+Applications may also need to declare the permissions they require. Permissions are
+specified as sub-attributes of a ``permission`` property, defined at the level of an
+project, app, or platform. Permission declarations are *cumulative*; if an application
+defines permissions at the global level, application level, *and* platform level, the
+final set of permissions will be the *merged* set of all permissions from all levels,
+starting from least to most specific, with the most specific taking priority.
+
+Briefcase maintains a set of cross-platform permissions:
+
+* ``permission.camera`` - permission to access to the camera to take photos or video.
+* ``permission.microphone`` - permission to access the microphone.
+* ``permission.coarse_location`` - permission to determine a rough GPS location.
+* ``permission.fine_location`` - permission to determine a precise GPS location.
+* ``permission.background_location`` - permission to track GPS location while in the background.
+* ``permission.photo_library`` - permission to access to the user's photo library.
+
+If a cross-platform permission is used, it will be mapped to platform-specific values in
+whatever files are used to define permissions on that platform.
+
+Permissions can also be configured by adding platform-specific configuration items. See the documentation for the the platform backends to see the options that are available.
+
+The value for each permission is a short description of why that permission is required.
+If the platform requires, the value may be displayed to the user as part of an
+authorization dialog. This description should describe *why* the app requires the
+permission, rather than a generic description of the permission being requested.
+
+The use of permissions may also imply other settings in your app. See the individual
+platform backends for details on how cross-platform permissions are mapped.
+
 Document types
 ==============
 
@@ -498,7 +530,7 @@ will use ``resources/icon.icns`` on macOS, and ``resources/icon.ico`` on
 Windows.
 
 Some platforms also require different *variants* (e.g., both square and round
-icons). These variants can be specified by qualifying the icon specification:
+icons). These variants can be specified by qualifying the icon specification::
 
     icon.round = "resource/round-icon"
     icon.square = "resource/square-icon"

docs/reference/platforms/android/gradle.rst

@@ -117,9 +117,85 @@ Android allows for some customization of the colors used by your app:
 Application configuration
 =========================
 
-The following options can be added to the
-``tool.briefcase.app.<appname>.android`` section of your ``pyproject.toml``
-file.
+The following options can be added to the ``tool.briefcase.app.<appname>.android``
+section of your ``pyproject.toml`` file.
+
+``android_manifest_attrs_extra_content``
+----------------------------------------
+
+Additional attributes that will be added verbatim to the ``<manifest>`` declaration of
+the ``AndroidManifest.xml`` of your app.
+
+``android_manifest_extra_content``
+----------------------------------
+
+Additional content that will be added verbatim just before the closing ``</manifest>``
+declaration of the ``AndroidManifest.xml`` of your app.
+
+``android_manifest_application_attrs_extra_content``
+----------------------------------------------------
+
+Additional attributes that will be added verbatim to the ``<application>`` declaration
+of the ``AndroidManifest.xml`` of your app.
+
+``android_manifest_application_extra_content``
+----------------------------------------------
+
+Additional content that will be added verbatim just before the closing
+``</application>`` declaration of the ``AndroidManifest.xml`` of your app.
+
+``android_manifest_activity_attrs_extra_content``
+-------------------------------------------------
+
+Additional attributes that will be added verbatim to the ``<activity>`` declaration of
+the ``AndroidManifest.xml`` of your app.
+
+``android_manifest_activity_extra_content``
+-------------------------------------------
+
+Additional content that will be added verbatim just before the closing ``</activity>``
+declaration of the ``AndroidManifest.xml`` of your app.
+
+``build_gradle_extra_content``
+------------------------------
+
+A string providing additional Gradle settings to use when building your app.
+This will be added verbatim to the end of your ``app/build.gradle`` file.
+
+``feature``
+-----------
+
+A property whose sub-properties define the features that will be marked as required by
+the final app. Each entry will be converted into a ``<uses-feature>`` declaration in
+your app's ``AndroidManifest.xml``, with the feature name matching the name of the
+sub-attribute.
+
+For example, specifying::
+
+    feature."android.hardware.bluetooth" = true
+
+will result in an ``AndroidManifest.xml`` declaration of::
+
+    <uses-feature android:name="android.hardware.bluetooth" android:required="true">
+
+The use of some cross-platform permissions will imply the addition of features; see
+:ref:`the discussion on Android permissions <android-permissions>` for more details.
+
+``permission``
+--------------
+
+A property whose sub-properties define the platform-specific permissions that will be
+marked as required by the final app. Each entry will be converted into a
+``<uses-permission>`` declaration in your app's ``AndroidManifest.xml``, with the
+feature name matching the name of the sub-attribute.
+
+For example, specifying::
+
+    permission."android.permission.HIGH_SAMPLING_RATE_SENSORS" = true
+
+will result in an ``AndroidManifest.xml`` declaration of::
+
+    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS">
 
 ``version_code``
 ----------------
@@ -197,18 +273,47 @@ continue to run in the background, but there will be no visual manifestation
 that it is running. It may also be useful as a cleanup mechanism when running
 in a CI configuration.
 
-Application configuration
-=========================
+.. _android-permissions:
+
+Permissions
+===========
 
-The following options can be added to the
-``tool.briefcase.app.<appname>.android`` section of your ``pyproject.toml``
-file:
+Briefcase cross platform permissions map to ``<uses-permission>`` declarations in the
+app's ``AppManifest.xml``:
 
-``build_gradle_extra_content``
-------------------------------
+* ``camera``: ``android.permission.CAMERA``
+* ``microphone``: ``android.permission.RECORD_AUDIO``
+* ``coarse_location``: ``android.permission.ACCESS_COARSE_LOCATION``
+* ``fine_location``: ``android.permission.ACCESS_FINE_LOCATION``
+* ``background_location``: ``android.permission.ACCESS_BACKGROUND_LOCATION``
+* ``photo_library``: ``android.permission.READ_MEDIA_VISUAL_USER_SELECTED``
 
-A string providing additional Gradle settings to use when building your app.
-This will be added verbatim to the end of your ``app/build.gradle`` file.
+Every application will be automatically granted the ``android.permission.INTERNET`` and
+``android.permission.NETWORK_STATE`` permissions.
+
+Specifying a ``camera`` permission will result in the following non-required ``feature``
+definitions being implicitly added to your app:
+
+* ``android.hardware.camera``,
+* ``android.hardware.camera.any``,
+* ``android.hardware.camera.front``,
+* ``android.hardware.camera.external`` and
+* ``android.hardware.camera.autofocus``.
+
+Specifying the ``coarse_location``, ``fine_location`` or ``background_location``
+permissions will result in the following non-required ``feature`` declarations being
+implicitly added to your app:
+
+* ``android.hardware.location.network``
+* ``android.hardware.location.gps``
+
+This is done to ensure that an app is not prevented from installing if the device
+doesn't have the given features. You can make the feature explicitly required by
+manually defining these feature requirements. For example, to make GPS hardware
+required, you could add the following to the Android section of your
+``pyproject.toml``::
+
+    feature."android.hardware.location.gps" = True
 
 Platform quirks
 ===============

docs/reference/platforms/iOS/xcode.rst

@@ -64,6 +64,42 @@ run
 The device simulator to target. Can be either a UDID, a device name (e.g.,
 ``"iPhone 11"``), or a device name and OS version (``"iPhone 11::iOS 13.3"``).
 
+Application configuration
+=========================
+
+The following options can be added to the ``tool.briefcase.app.<appname>.iOS.app``
+section of your ``pyproject.toml`` file.
+
+``info``
+--------
+
+A property whose sub-attributes define keys that will be added to the app's
+``Info.plist`` file. Each entry will be converted into a key in the entitlements
+file. For example, specifying::
+
+    info."UIFileSharingEnabled" = true
+
+will result in an ``Info.plist`` declaration of::
+
+    <key>UIFileSharingEnabled</key><true/>
+
+Any Boolean or string value can be used for an ``Info.plist`` value.
+
+Permissions
+===========
+
+Briefcase cross platform permissions map to the following ``info`` keys:
+
+* ``camera``: ``NSCameraUsageDescription``
+* ``microphone``: ``NSMicrophoneUsageDescription``
+* ``coarse_location``: ``NSLocationDefaultAccuracyReduced=True`` if ``fine_location`` is
+  not defined, plus ``NSLocationWhenInUseUsageDescription`` if ``background_location``
+  is not defined
+* ``fine_location``: ``NSLocationDefaultAccuracyReduced=False``, plus
+  ``NSLocationWhenInUseUsageDescription`` if ``background_location`` is not defined
+* ``background_location``: ``NSLocationAlwaysAndWhenInUseUsageDescription``
+* ``photo_library``: ``NSPhotoLibraryAddUsageDescription``
+
 Platform quirks
 ===============
 

docs/reference/platforms/linux/flatpak.rst

@@ -77,6 +77,35 @@ The following options can be added to the
 ``tool.briefcase.app.<appname>.linux.flatpak`` section of your
 ``pyproject.toml`` file:
 
+``finish_arg``
+~~~~~~~~~~~~~~
+
+The arguments used to configure the Flatpak sandbox. ``finish_arg`` is an attribute
+that can have additional sub-attributes; each sub-attribute maps to a single property
+that will be added to the app's manifest. For example, to add ``--allow=bluetooth`` as a
+finish argument, you would specify::
+
+    finish_arg."allow=bluetooth" = True
+
+Briefcase adds the following finish arguments by default:
+
+* ``share=ipc``
+* ``socket=x11``
+* ``nosocket=wayland``
+* ``share=network``
+* ``device=dri``
+* ``socket=pulseaudio``
+* ``filesystem=xdg-cache``
+* ``filesystem=xdg-config``
+* ``filesystem=xdg-data``
+* ``filesystem=xdg-documents``
+* ``socket=session-bus``
+
+These can be disabled by explicitly setting their value to ``False``; for example, to
+disable audio access, you would specify::
+
+    finish_arg."socket=pulseaudio" = false
+
 ``flatpak_runtime_repo_alias``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -115,6 +144,18 @@ build the Flatpak app.
 The Flatpak runtime and SDK are paired; so, both a ``flatpak_runtime`` and a
 corresponding ``flatpak_sdk`` must be defined.
 
+``modules_extra_content``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Additional build instructions that will be inserted into the Flatpak manifest, *after*
+Python has been installed and ``pip`` is guaranteed to exist, but *before* any app code
+or app packages have been installed into the Flatpak.
+
+Permissions
+===========
+
+Permissions are not used for Flatpak packaging.
+
 Compilation issues with Flatpak
 ===============================
 

docs/reference/platforms/macOS/app.rst

@@ -59,6 +59,46 @@ Application configuration
 The following options can be added to the ``tool.briefcase.app.<appname>.macOS.app``
 section of your ``pyproject.toml`` file.
 
+``entitlement``
+~~~~~~~~~~~~~~~
+
+A property whose sub-attributes define keys that will be added to the app's
+``Entitlements.plist`` file. Each entry will be converted into a key in the entitlements
+file. For example, specifying::
+
+    entitlement."com.apple.vm.networking" = true
+
+will result in an ``Entitlements.plist`` declaration of::
+
+    <key>com.apple.vm.networking</key><true/>
+
+Any Boolean or string value can be used for an entitlement value.
+
+All macOS apps are automatically granted the following entitlements:
+
+* ``com.apple.security.cs.allow-unsigned-executable-memory``
+* ``com.apple.security.cs.disable-library-validation``
+
+You can disable these default entitlements by defining them manually. For example, to
+enable library validation, you could add the following to your ``pyproject.toml``::
+
+    entitlement."com.apple.security.cs.disable-library-validation" = false
+
+``info``
+~~~~~~~~
+
+A property whose sub-attributes define keys that will be added to the app's
+``Info.plist`` file. Each entry will be converted into a key in the entitlements
+file. For example, specifying::
+
+    info."NSAppleScriptEnabled" = true
+
+will result in an ``Info.plist`` declaration of::
+
+    <key>NSAppleScriptEnabled</key><true/>
+
+Any Boolean or string value can be used for an ``Info.plist`` value.
+
 ``universal_build``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -68,6 +108,24 @@ only be executable on the host platform on which it was built - i.e., if you bui
 an x86_64 machine, you will produce an x86_65 binary; if you build on an ARM64 machine,
 you will produce an ARM64 binary.
 
+Permissions
+===========
+
+Briefcase cross platform permissions map to a combination of ``info`` and ``entitlement``
+keys:
+
+* ``microphone``: an ``entitlement`` of ``com.apple.security.device.audio-input``
+* ``camera``: an ``entitlement`` of ``com.apple.security.device.camera``
+* ``coarse_location``: an ``info`` entry for ``NSLocationUsageDescription``
+  (ignored if ``background_location`` or ``fine_location`` is defined); plus an
+  entitlement of ``com.apple.security.personal-information.location``
+* ``fine_location``: an ``info`` entry for ``NSLocationUsageDescription``(ignored
+  if ``background_location`` is defined); plus an ``entitlement`` of
+  ``com.apple.security.personal-information.location``
+* ``background_location``: an ``info`` entry for ``NSLocationUsageDescription``;
+  plus an ``entitlement`` of ``com.apple.security.personal-information.location``
+* ``photo_library``: an ``entitlement`` of ``com.apple.security.personal-information.photos-library``
+
 Platform quirks
 ===============