sandbox-permissions: Add docs for conditional permissions

Fixes: flatpak/flatpak#6543

Author: bbhtt

docs/sandbox-permissions.rst

@@ -472,6 +472,181 @@ Note that these should not have subpaths in them unless the value
 of the subpath can be consistently pre-determined. Block device naming
 depends on the kernel/fstab configuration and cannot be pre-determined.
 
+Conditional permissions
+-----------------------
+
+Since 1.17.0.
+
+Some sandbox permissions support the conditional permissions system
+which allows them to be granted only when certain runtime conditions
+are satisfied or fallback otherwise. A permission can be
+
+- Unconditionally allowed
+- Unconditionally denied
+- Conditionally allowed, depending on runtime conditions
+
+Unconditionally allowing or denying a permission (for example
+through ``--socket=NAME`` or ``--nosocket=NAME``) will grant or revoke
+the permission outright without any conditional evaluation.
+
+The following permissions support the conditional system:
+``sockets``, ``devices``, ``share`` and ``allow``.
+
+Conditional permission syntax
+``````````````````````````````
+
+Conditional permissions are expressed using the
+``if:PERMISSION:CONDITION`` syntax in metadata, where they are merged
+with existing permission keys, and using the
+``--socket-if``, ``--device-if``, ``--share-if`` and ``--allow-if``
+options on the command line. The syntax in commandline is
+``--socket-if=PERMISSION:CONDITION`` and so on.
+
+.. note::
+
+   Older Flatpak versions will fail when encountering unknown
+   commandline options, while unrecognized metadata entries will be
+   silently ignored.
+
+   Flatpak manifests using conditional flags (for example
+   ``--socket-if`` etc.) will require Flatpak 1.17.0 or newer to
+   build and attempting to build them with older Flatpak versions will
+   produce an error.
+
+The following conditions are supported:
+
+- ``true`` - Always evaluates to true
+- ``false``- Always evaluates to false
+- ``has-input-device`` - ``true`` if the Flatpak version supports the
+  ``device=input`` permission (since 1.15.6), always true in Flatpak
+  versions supporting the conditional syntax and ``false`` otherwise.
+- ``has-wayland`` - ``true`` if the current desktop session supports
+  Wayland, ``false`` otherwise.
+
+For example, instead of the ``--socket=wayland`` permission which
+unconditionally allows access to the Wayland socket,
+``--socket-if=wayland:has-wayland`` can be used to only grant access to
+the socket when running in a Wayland desktop session.
+
+Conditions can be negated by prefixing with ``!``.
+
+For example, instead of the ``--socket=x11`` permission which
+unconditionally allows access to the X11 socket,
+``--socket-if=x11:!has-wayland`` can be used to only grant access to the
+socket when a Wayland desktop session is not available.
+
+Multiple conditionals can be specified for the same permission, in which
+case the permission is granted if any condition matches (OR logic). For
+example::
+
+    sockets=wayland;if:x11:!has-wayland;if:x11:!has-input-device;
+
+- ``wayland`` is unconditionally allowed
+- ``x11`` is allowed if Wayland is unavailable (``!has-wayland``)
+- ``x11`` is also allowed if the input device permission is unsupported
+  (``!has-input-device``)
+
+In commandline the flags are translated as::
+
+    --socket=wayland
+    --socket-if=x11:!has-wayland
+    --socket-if=x11:!has-input-device
+
+If no conditional rule evaluates to ``true``, the permission is denied
+unless it is also unconditionally allowed. Duplicate conditions are
+ignored and conditions are treated as an unordered set.
+
+For backward compatibility with older Flatpak versions, conditional
+permissions should be combined with unconditional permissions. The
+unconditional form should be included before conditionals. Older
+Flatpak versions will ignore conditional entries and see only the
+unconditional entries while newer versions will evaluate both and apply
+the conditional logic. For example::
+
+  sockets=x11;if:x11:!has-wayland;
+
+In commandline the flags are translated as::
+
+  --socket=x11
+  --socket-if=x11:!has-wayland
+
+The trade-off is that older Flatpak which does not understand
+the conditional syntax, will grant a broader permissions than intended
+while newer Flatpak will function correctly as intended.
+
+Examples
+`````````
+
+The pattern::
+
+  sockets=wayland;fallback-x11;
+
+can be translated to the conditional system (without backwards
+compatibility)::
+
+  sockets=wayland;if:x11:!has-wayland;
+
+The ``has-input-device`` condition can be used to fall back to
+``--device=all`` on older Flatpak versions that do not support
+``--device=input``::
+
+    devices=all;input;if:input:has-input-device;if:all:!has-input-device;
+
+- **Pre-1.15.6**: The ``input`` device permission is unsupported and
+  only ``all`` is recognised, granting access to all devices as a
+  fallback.
+
+- **1.15.6 to 1.17**: The ``all, input`` device permissions are supported
+  but conditional syntax is not understood. ``all`` takes precedence
+  over ``input`` granting access to all devices as a fallback.
+
+- **1.17+**: The conditional syntax is understood. The
+  ``has-input-device`` condition evaluates to true so ``input`` is
+  granted. The ``!has-input-device`` condition evaluates to false so
+  ``all`` is not granted. Therefore, only ``input`` device access is
+  granted.
+
+In commandline the flags are translated as::
+
+  --device=all
+  --device=input
+  --device-if=input:has-input-device
+  --device-if=all:!has-input-device
+
+To explicitly deny a permission that might be granted through runtime
+metadata or overrides, the permission can be prefixed with ``!``::
+
+    socket=!x11;
+
+This denial can be combined with conditional grants to remove
+unconditional access while allowing conditional access::
+
+    sockets=!x11;x11;if:x11:!has-wayland;
+
+This denies unconditional X11 access but allows X11 conditionally when
+Wayland is unavailable. The ``x11`` and ``!x11`` entries ensure
+backwards compatibility as older Flatpak versions see the ``x11`` grant
+and allow X11 unconditionally, while newer versions recognize the
+conditional logic.
+
+In commandline the flags are translated as::
+
+  --nosocket=x11
+  --socket=x11
+  --socket-if=x11:!has-wayland
+
+fallback-x11 socket
+````````````````````
+
+The ``fallback-x11`` socket, on pre-1.17 Flatpak versions implicitly
+granted ``x11`` access and at runtime X11 access was suppressed when
+Wayland was available, while on newer Flatpak (1.17+) it is internally
+converted to the conditional syntax ``if:x11:!has-wayland``. When saving
+the metadata, Flatpak converts ``if:x11:!has-wayland`` back to
+``fallback-x11`` only when it is the sole conditional on ``x11``. If
+additional conditionals are present, the new syntax is written directly
+and older Flatpak versions will not understand the conditional entries.
+
 .. rubric:: Footnotes
 
 .. [#f1] This is not necessarily required, but without it the X11 shared