scope/polkit: add service module to write PolKit agents

Author: Cu3PO42

BUILD.md

@@ -192,6 +192,13 @@ To disable: `-DSERVICE_PAM=OFF`
 
 Dependencies: `pam`
 
+### Polkit
+This feature enables creating Polkit agents that can prompt user for authentication.
+
+To disable: `-DSERVICE_POLKIT=OFF`
+
+Dependencies: `polkit-qt-1`
+
 ### Hyprland
 This feature enables hyprland specific integrations. It requires wayland support
 but has no extra dependencies.

CMakeLists.txt

@@ -67,6 +67,7 @@ boption(SERVICE_STATUS_NOTIFIER "System Tray" ON)
 boption(SERVICE_PIPEWIRE "PipeWire" ON)
 boption(SERVICE_MPRIS "Mpris" ON)
 boption(SERVICE_PAM "Pam" ON)
+boption(SERVICE_POLKIT "Polkit" ON)
 boption(SERVICE_GREETD "Greetd" ON)
 boption(SERVICE_UPOWER "UPower" ON)
 boption(SERVICE_NOTIFICATIONS "Notifications" ON)

default.nix

@@ -10,6 +10,7 @@
   ninja,
   spirv-tools,
   qt6,
+  kdePackages,
   breakpad,
   jemalloc,
   cli11,
@@ -43,6 +44,7 @@
   withPam ? true,
   withHyprland ? true,
   withI3 ? true,
+  withPolkit ? true,
 }: let
   unwrapped = stdenv.mkDerivation {
     pname = "quickshell${lib.optionalString debug "-debug"}";
@@ -76,7 +78,8 @@
     ++ lib.optionals (withWayland && libgbm != null) [ libdrm libgbm ]
     ++ lib.optional withX11 xorg.libxcb
     ++ lib.optional withPam pam
-    ++ lib.optional withPipewire pipewire;
+    ++ lib.optional withPipewire pipewire
+    ++ lib.optional withPolkit kdePackages.polkit-qt-1;
 
     cmakeBuildType = if debug then "Debug" else "RelWithDebInfo";
 
@@ -91,6 +94,7 @@
       (lib.cmakeBool "SCREENCOPY" (libgbm != null))
       (lib.cmakeBool "SERVICE_PIPEWIRE" withPipewire)
       (lib.cmakeBool "SERVICE_PAM" withPam)
+      (lib.cmakeBool "SERVICE_POLKIT" withPolkit)
       (lib.cmakeBool "HYPRLAND" withHyprland)
       (lib.cmakeBool "I3" withI3)
     ];

quickshell.scm

@@ -42,6 +42,7 @@
                   libxcb
                   libxkbcommon
                   linux-pam
+                  polkit-qt
                   mesa
                   pipewire
                   qtbase

src/services/CMakeLists.txt

@@ -14,6 +14,10 @@ if (SERVICE_PAM)
 	add_subdirectory(pam)
 endif()
 
+if (SERVICE_POLKIT)
+	add_subdirectory(polkit)
+endif()
+
 if (SERVICE_GREETD)
 	add_subdirectory(greetd)
 endif()

src/services/polkit/CMakeLists.txt

@@ -0,0 +1,23 @@
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(polkit REQUIRED IMPORTED_TARGET polkit-qt6-core-1 polkit-qt6-agent-1)
+
+qt_add_library(quickshell-service-polkit STATIC
+	qml.cpp
+)
+
+qt_add_qml_module(quickshell-service-polkit
+	URI Quickshell.Services.Polkit
+	VERSION 0.1
+	DEPENDENCIES QtQml
+)
+
+install_qml_module(quickshell-service-polkit)
+
+target_link_libraries(quickshell-service-polkit PRIVATE
+	Qt::Qml PkgConfig::polkit
+	Qt::Quick # pch
+)
+
+qs_module_pch(quickshell-service-polkit)
+
+target_link_libraries(quickshell PRIVATE quickshell-service-polkitplugin)

src/services/polkit/module.md

@@ -0,0 +1,50 @@
+name = "Quickshell.Services.Polkit"
+description = "Polkit API"
+headers = [qml.hpp]
+-----
+
+## Purpose of a Polkit Agent
+
+PolKit is a system for privileged applications to query if a user is permitted to execute an action.
+You have probably seen it in the form of a "Please enter your password to continue with X" dialog box before.
+This dialog box is presented by your *PolKit agent*, it is a process running as your user that accepts authentication requests from the *daemon* and presents them to you to accept or deny.
+
+This service enables writing a PolKit agent in Quickshell.
+
+## Implementing a Polkit Agent
+
+The backend logic of communicating with the daemon is handled by the @@PolkitAgent object.
+It exposes incoming requests as properties and provides appropriate signals.
+
+### Flow of an authentication request
+
+Incoming authentication requests are queued in the order that they arrive.
+If none is queued, a request starts processing right away.
+Otherwise, it will wait until prior requests are done.
+
+A request starts by emitting the @@PolkitAgent.authenticationRequestStarted signal.
+At this point, information like the action to be performed and permitted users that can authenticate is available.
+
+An authentication *session* for the request is immediately started, which internally starts a PAM conversation that is likely to prompt for user input.
+* Additional prompts may be shared with the user by way of the @@PolkitAgent.subMessageChanged signal and the @@PolkitAgent.subMessage property. A common message might be 'Please input your password'.
+* An input request is forwarded via the @@PolkitAgent.inputRequestChanged signal and @@PolkitAgent.inputRequest property. Note that the request specifies whether the text box should show the typed input on screen or replace it with placeholders.
+
+User replies can be submitted via the @@PolkitAgent.submit method.
+A conversation can take multiple turns, for example if second factors are involved.
+
+If authentication fails, we automatically create a fresh session so the user can try again.
+The @@PolkitAgent.authenticationFailed signal is emitted in this case.
+
+If authentication is successful, you receive the @@PolkitAgent.authenticationSucceeeded signal. At this point, the dialog can be closed.
+If additional requests are queued, you will receive the @@PolkitAgent.authenticationRequestStarted signal again.
+
+#### Cancelled requests
+
+Requests may either be canceled by the user or the PolKit daemon.
+In this case, we clean up any state and proceed to the next request, if any.
+
+If the request was cancelled by the daemon and not the user, you also receive the @@PolkitAgent.authenticationRequestCancelled signal.
+
+## Limitations
+
+- If multiple authentication requests are queued, we cannot determine which one is canceled (if one is canceled)