### Build and Install Commands

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Commands to compile the project and install the resulting binaries and service files.

```bash
cmake -B build
cmake --build build
```

```bash
sudo cmake --install build
```

--------------------------------

### Usage Example for CPolkitListener

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Demonstrates initializing the backend and registering the listener agent.

```cpp
auto backend = IBackend::create();
CPolkitListener listener;
if (!listener.registerAgent(backend)) {
    // Failed to register; exit
    return false;
}
// Now ready to receive authentication requests
```

--------------------------------

### Installation and Configuration

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/CMakeLists.txt

Configures service files and defines installation paths for the executable and systemd/dbus services.

```cmake
include(GNUInstallDirs)
set(LIBEXECDIR ${CMAKE_INSTALL_FULL_LIBEXECDIR})
configure_file(assets/hyprpolkitagent-service.in hyprpolkitagent.service @ONLY)
configure_file(assets/hyprpolkitagent-dbus.in hyprpolkitagent-dbus.service @ONLY)

install(TARGETS hyprpolkitagent
        DESTINATION ${CMAKE_INSTALL_LIBEXECDIR})
install(FILES ${CMAKE_BINARY_DIR}/hyprpolkitagent.service
        DESTINATION "lib/systemd/user")
install(FILES ${CMAKE_BINARY_DIR}/hyprpolkitagent-dbus.service
        DESTINATION ${CMAKE_INSTALL_DATADIR}/dbus-1/services
        RENAME org.hyprland.hyprpolkitagent.service)
```

--------------------------------

### Configuration File Examples

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Examples of the Hyprlang configuration file format and the default values applied when keys are omitted.

```text
general {
    password_field_width = 300
    window_width         = 600
    window_height        = 500
    show_details         = true
}
```

```text
general {
    password_field_width = 340
    window_width         = 520
    window_height        = 440
    show_details         = true
}
```

--------------------------------

### Initialize SAuthRequest

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Example of populating an SAuthRequest structure with sample data.

```cpp
SAuthRequest req{
    actionId = "org.freedesktop.systemd1.manage-units",
    message = "Authentication is required to manage system services.",
    iconName = "dialog-password",
    cookie = "1234567890abcdef",
    identities = { SIdentity{"unix-user:1000", "alice", 1000} },
    command = "/usr/bin/systemctl start nginx.service",
    details = { {"exe", "/usr/bin/systemctl"}, {"pid", "1234"} },
    vendor = "The systemd Project",
    vendorUrl = "https://systemd.io"
};
```

--------------------------------

### Initialize and load configuration

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Basic usage example for instantiating the manager and loading the configuration file.

```cpp
CConfigManager manager;
manager.load();
```

--------------------------------

### Initialize SIdentity

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Example of manually creating an SIdentity instance.

```cpp
CPolkitListener::SIdentity id;
id.raw = "unix-user:1000";
id.uid = 1000;
id.display = "alice";
```

--------------------------------

### Access configuration values

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Example demonstrating how to initialize the manager, load settings, and retrieve specific configuration values.

```cpp
g_pConfigManager = std::make_unique<CConfigManager>();
g_pConfigManager->load();
auto cfg = g_pConfigManager->get();
int width = cfg.windowWidth;
```

--------------------------------

### Initiate Authentication via Python

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Example of calling the BeginAuthentication method using the dbus-python library.

```python
import dbus

bus = dbus.SystemBus()
authority = bus.get_object(
    'org.freedesktop.PolicyKit1',
    '/org/freedesktop/PolicyKit1/Authority'
)
authority_iface = dbus.Interface(
    authority,
    'org.freedesktop.PolicyKit1.Authority'
)

agent = bus.get_object(
    'org.hyprland.hyprpolkitagent',
    '/org/hyprland/PolicyKit1/AuthenticationAgent'
)
agent_iface = dbus.Interface(
    agent,
    'org.freedesktop.PolicyKit1.AuthenticationAgent'
)

identities = [
    ('unix-user', {'uid': dbus.UInt32(1000)})
]

agent_iface.BeginAuthentication(
    action_id='org.freedesktop.systemd1.manage-units',
    message='Authentication required to manage systemd units',
    icon_name='dialog-password',
    details={},
    cookie='12345abcde',
    identities=identities,
    dbus_interface='org.freedesktop.PolicyKit1.AuthenticationAgent'
)
```

--------------------------------

### Service Management

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Commands to start and enable the agent as a systemd user service.

```bash
systemctl --user start hyprpolkitagent
systemctl --user enable hyprpolkitagent
```

--------------------------------

### Example Error Log

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Shows the format of error logs generated when the configuration file fails to parse.

```text
hyprpolkitagent: config parse error: <details>
```

--------------------------------

### Start CAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Initializes the agent and registers with D-Bus. This is a blocking call that enters the event loop.

```cpp
bool CAgent::start()
```

```cpp
g_pAgent = std::make_unique<CAgent>();
if (!g_pAgent->start()) {
    // Failed to register or initialize
    return 1;
}
// Never returns; blocks in event loop
```

--------------------------------

### Authentication Message Example

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Example of a message string used by the extraction heuristics to identify commands.

```text
You are required to authenticate to run a program
```

--------------------------------

### View Agent Registration Output

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Example of the diagnostic output logged to stderr during agent registration.

```text
registered polkit agent for session c1 (helper-socket=yes helper-path=/usr/lib/polkit-1/polkit-agent-helper-1 setuid=yes)
```

--------------------------------

### Cancel Authentication via Python

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Example of calling the CancelAuthentication method using the dbus-python library.

```python
agent_iface.CancelAuthentication(
    cookie='12345abcde',
    dbus_interface='org.freedesktop.PolicyKit1.AuthenticationAgent'
)
```

--------------------------------

### BeginAuthentication

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Called by PolicyKit when an action requires authentication. This method triggers the display of the password dialog and starts the PAM helper.

```APIDOC
## BeginAuthentication

### Description
Called by PolicyKit when an action requires authentication. Parses request parameters, displays the password dialog, and starts the PAM helper.

### Method
D-Bus Method Call

### Interface
org.freedesktop.PolicyKit1.AuthenticationAgent

### Parameters
- **action_id** (string) - Required - PolicyKit action ID
- **message** (string) - Required - User-facing message
- **icon_name** (string) - Required - Icon name for the dialog
- **details** (dict) - Required - Additional context as key-value pairs
- **cookie** (string) - Required - Unique opaque cookie for this authentication
- **identities** (array of structs) - Required - List of identities that can authenticate
```

--------------------------------

### CAgent::start()

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Initializes the agent, loads configuration, creates the rendering backend, and registers with D-Bus as a polkit authentication agent.

```APIDOC
## bool CAgent::start()

### Description
Initializes the agent, loads configuration, creates the rendering backend, and registers with D-Bus as a polkit authentication agent. This method enters the event loop and blocks until shutdown.

### Returns
- **bool** - true if initialization succeeded, false if any step failed (backend creation, D-Bus registration, or entering event loop).
```

--------------------------------

### Initialize and Use CAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Demonstrates initializing the agent in main and invoking methods from callbacks.

```cpp
// In src/main.cpp
g_pAgent = std::make_unique<CAgent>();
g_pAgent->start();

// From any callback
g_pAgent->submitPassword(password);
```

--------------------------------

### Project Initialization and Dependencies

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/CMakeLists.txt

Sets the minimum CMake version, project metadata, C++ standard, and required system dependencies via PkgConfig.

```cmake
cmake_minimum_required(VERSION 3.16)

file(READ "${CMAKE_SOURCE_DIR}/VERSION" VER_RAW)
string(STRIP ${VER_RAW} VER)

project(hpa VERSION ${VER} LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(PkgConfig REQUIRED)

pkg_check_modules(deps REQUIRED IMPORTED_TARGET
    hyprutils
    hyprtoolkit
    hyprgraphics
    hyprlang
    pixman-1
    libdrm
    sdbus-c++>=2
)
```

--------------------------------

### Construct and display a CDialog

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Initializes a new authentication dialog with a request and backend, then makes it visible to the user.

```cpp
auto dialog = std::make_unique<CDialog>(authRequest, backend);
dialog->show();
```

--------------------------------

### Begin Authentication Session

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Initiates an authentication session by displaying a password dialog for the provided request.

```cpp
void CAgent::beginAuth(CPolkitListener::SAuthRequest req)
```

```cpp
CPolkitListener::SAuthRequest req = /* populated from D-Bus */;
g_pAgent->beginAuth(req);
// Dialog is now visible and waiting for user input
```

--------------------------------

### Initialize and Access CConfigManager

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Demonstrates the initialization of the config manager in the agent startup and its usage within dialog builders to retrieve configuration values.

```cpp
// In CAgent::start()
static CConfigManager s_configManager;
g_pConfigManager = &s_configManager;
g_pConfigManager->load();

// In CDialog::buildPasswordField()
const auto& cfg = g_pConfigManager->get();
auto field = CTextboxBuilder::begin()
    ->size({CDynamicSize::HT_SIZE_ABSOLUTE, CDynamicSize::HT_SIZE_ABSOLUTE,
            {(double)cfg.passwordFieldWidth, 36.0}})
    ->commence();

// In CDialog::build()
const auto& cfg = g_pConfigManager->get();
auto window = CWindowBuilder::begin()
    ->preferredSize({(double)cfg.windowWidth, (double)cfg.windowHeight})
    ->commence();
```

--------------------------------

### CAgent::beginAuth()

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Begins an authentication session by creating and showing the password dialog for a given authentication request.

```APIDOC
## void CAgent::beginAuth(CPolkitListener::SAuthRequest req)

### Description
Begins an authentication session by creating and showing the password dialog for a given authentication request. The dialog will call back to the agent as the user interacts.

### Parameters
- **req** (CPolkitListener::SAuthRequest) - Required - Authentication request details including action ID, message, identities, and command.
```

--------------------------------

### Handle PAM_PROMPT_ECHO_ON

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Requests visible input from the user. The agent responds by writing the response to stdin.

```text
PAM_PROMPT_ECHO_ON <prompt_text>
```

```text
PAM_PROMPT_ECHO_ON Enter verification code:
PAM_PROMPT_ECHO_ON Device name:
```

```text
<response>
```

--------------------------------

### Initialize CAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Constructs the agent instance.

```cpp
CAgent::CAgent()
```

--------------------------------

### Set XDG_CONFIG_HOME environment variable

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Defines the base directory for user configuration files, overriding the default ~/.config path.

```bash
export XDG_CONFIG_HOME=/etc/user/config
# Agent now reads from /etc/user/config/hyprpolkitagent/hyprpolkitagent.conf
```

--------------------------------

### Construct CPolkitListener

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Initializes the listener and ignores SIGPIPE signals. Does not establish D-Bus connections until registration.

```cpp
CPolkitListener::CPolkitListener()
```

--------------------------------

### Configure Compact Dialog Layout

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Sets a smaller window size and hides authentication details by default.

```ini
general {
    password_field_width = 250
    window_width         = 450
    window_height        = 350
    show_details         = 0
}
```

--------------------------------

### Project File Structure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Displays the directory layout of the source code.

```text
src/
├── main.cpp                  Entry point; creates g_pAgent
├── core/
│   ├── Agent.hpp/cpp         CAgent class
│   ├── PolkitListener.hpp/cpp  CPolkitListener class (D-Bus + PAM)
├── ui/
│   ├── Dialog.hpp/cpp        CDialog class (password entry)
└── config/
    ├── Config.hpp/cpp        CConfigManager class
```

--------------------------------

### Configure hyprpolkitagent settings

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/INDEX.md

Configuration file format for defining UI dimensions and display preferences in ~/.config/hyprpolkitagent/hyprpolkitagent.conf.

```text
general {
    password_field_width = 340  (pixels)
    window_width         = 520  (pixels)
    window_height        = 440  (pixels)
    show_details         = 1    (0 or 1)
}
```

--------------------------------

### Handle authentication request

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Implementation of CAgent::beginAuth to display an authentication dialog.

```cpp
void CAgent::beginAuth(CPolkitListener::SAuthRequest req) {
    // req contains all info needed to display the auth dialog
    m_dialog = CUniquePointer<CDialog>(new CDialog(req, m_backend));
    m_dialog->show();
}
```

--------------------------------

### Load configuration method

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

The load method parses the configuration file using the Hyprlang parser and populates the internal settings.

```cpp
void CConfigManager::load()
```

--------------------------------

### Configure Large Dialog with Full Details

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Increases window dimensions and enables the display of authentication details.

```ini
general {
    password_field_width = 400
    window_width         = 600
    window_height        = 500
    show_details         = 1
}
```

--------------------------------

### Handle fork and exec failure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Manages process creation errors during helper execution, returning failure if fork or exec fails.

```cpp
pid_t pid = fork();
if (pid < 0) {
    return false;  // Fork failed
}
if (pid == 0) {
    execl(helper, ...);
    _exit(127);  // Exec failed
}
```

--------------------------------

### CAgent::backend

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Retrieves the rendering and input backend instance.

```APIDOC
## Hyprutils::Memory::CSharedPointer<Hyprtoolkit::IBackend> CAgent::backend()

### Description
Returns a shared pointer to the rendering and input backend.

### Returns
- **CSharedPointer<IBackend>** - Backend for rendering and event loop

### Example
```cpp
auto backend = g_pAgent->backend();
auto colors = backend->getPalette()->m_colors;
```
```

--------------------------------

### Accessing SHPAConfig

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Retrieves the current configuration instance from the global config manager.

```cpp
const auto& cfg = g_pConfigManager->get();
int width = cfg.windowWidth;
bool showDetails = cfg.showDetails;
```

--------------------------------

### Visualize Module Relationships

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Diagram showing the interaction between D-Bus, the agent coordinator, UI components, and the PAM stack.

```text
D-Bus (systemd/PolicyKit)
    ↓
CPolkitListener (listens for auth requests)
    ↓
CAgent (main coordinator)
    ├─→ CDialog (password entry UI)
    │   ├─→ Hyprtoolkit Backend (rendering, input)
    │   └─→ CConfigManager (sizes, layout options)
    └─→ PAM Helper (privilege escalation)
        └─→ PAM Stack (kernel password verification)
```

--------------------------------

### Handle Authentication Request

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Updates the password field prompt and configures input visibility based on PAM helper output.

```cpp
// Called by the PAM helper when it needs a password
g_pAgent->onRequest("Enter password: ", false);
// Password field updates to accept hidden input
```

--------------------------------

### Initialize and manage CDialog authentication flow

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Instantiate the dialog and update its state during the authentication process, including handling prompts and error messages.

```cpp
auto dialog = std::make_unique<CDialog>(authRequest, backend);
dialog->show();

// PAM helper requests a password
dialog->setPrompt("Password: ", false);

// User enters incorrect password
dialog->setError("Authentication failed");

// Helper restarts for retry
dialog->setPrompt("Password: ", false);
dialog->setInfo("");  // Clear previous state
```

--------------------------------

### Restart hyprpolkitagent service

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Required command to apply configuration changes.

```bash
systemctl --user restart hyprpolkitagent
```

--------------------------------

### void CDialog::setInfo(const std::string& text)

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Displays or clears informational text in the dialog.

```APIDOC
## void CDialog::setInfo(const std::string& text)

### Description
Displays informational text in the dialog (e.g., "Please wait for 2FA").

### Parameters
- **text** (const std::string&) - Required - Information message

### Returns
- void

### Example
```cpp
dialog->setInfo("Sending verification code...");
```
```

--------------------------------

### Configure hyprpolkitagent settings

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/README.md

Define general settings for the authentication agent in the configuration file. Changes require an agent restart to take effect.

```hyprlang
general {
    password_field_width = 340
    window_width         = 520
    window_height        = 440
    show_details         = true
}
```

--------------------------------

### CDialog::show

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Displays the authentication dialog window and focuses the password input field.

```APIDOC
## CDialog::show

### Description
Opens the dialog window on the primary display and focuses the password field for user input.

### Signature
void CDialog::show()

### Returns
- **void**

### Example
```cpp
dialog->show();
```
```

--------------------------------

### Select Identity in CAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Switches the authentication identity and restarts the PAM helper.

```cpp
// User selects a different user from the dropdown
g_pAgent->selectIdentity("unix-user:0");
```

--------------------------------

### Executable Definition and Linking

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/CMakeLists.txt

Defines the project executable and links the previously identified PkgConfig dependencies.

```cmake
add_executable(hyprpolkitagent
    src/main.cpp
    src/config/Config.cpp
    src/config/Config.hpp
    src/core/Agent.cpp
    src/core/Agent.hpp
    src/core/PolkitListener.cpp
    src/core/PolkitListener.hpp
    src/ui/Dialog.cpp
    src/ui/Dialog.hpp
)

target_link_libraries(hyprpolkitagent PRIVATE PkgConfig::deps)
```

--------------------------------

### Register PolicyKit Agent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Connects to D-Bus and registers the agent with the PolicyKit Authority. Requires a valid backend for event loop integration.

```cpp
bool CPolkitListener::registerAgent(
    Hyprutils::Memory::CSharedPointer<Hyprtoolkit::IBackend> backend
)
```

--------------------------------

### Send User Input to Helper

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

The agent sends raw user input to the helper via stdin.

```text
<user_input>
```

```text
my_password
```

--------------------------------

### Show the dialog window

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Displays the dialog on the primary display and sets focus to the password input field.

```cpp
dialog->show();
// Window is now visible and password field accepts input
```

--------------------------------

### Construct CConfigManager

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

The constructor initializes the manager and resolves the configuration file path without loading the file.

```cpp
CConfigManager::CConfigManager()
```

--------------------------------

### Configure authentication window height

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Sets the base height of the dialog. Additional space is pre-allocated if details are enabled.

```ini
general {
    window_height = 480
}
```

--------------------------------

### Authentication Testing

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/README.md

Commands to trigger PolicyKit authentication requests for testing purposes.

```bash
pkexec echo "Authentication successful"
```

```bash
pkexec systemctl status nginx
pkexec usermod -aG docker $(whoami)
```

--------------------------------

### Access CAgent Backend

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Retrieves the rendering and input backend used for palette and event handling.

```cpp
auto backend = g_pAgent->backend();
auto colors = backend->getPalette()->m_colors;
```

--------------------------------

### RegisterAuthenticationAgent D-Bus Method

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Registers the agent with the PolicyKit Authority during startup.

```dbus
org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent(
    (s a{s v}) subject,
    s locale,
    o object_path
) -> ()
```

--------------------------------

### CDialog Constructor

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Constructs a new authentication dialog instance using an authentication request and a backend.

```APIDOC
## CDialog::CDialog

### Description
Constructs a dialog for a given authentication request and backend. The dialog is initialized but remains hidden until show() is called.

### Signature
CDialog(const CPolkitListener::SAuthRequest& req, Hyprutils::Memory::CSharedPointer<Hyprtoolkit::IBackend> backend)

### Parameters
- **req** (const SAuthRequest&) - Required - Authentication request containing action, message, identities, command, and details.
- **backend** (CSharedPointer<IBackend>) - Required - Hyprtoolkit backend for rendering and event loop.

### Example
```cpp
auto dialog = std::make_unique<CDialog>(authRequest, backend);
dialog->show();
```
```

--------------------------------

### void CDialog::setPrompt(const std::string& text, bool echo)

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Updates the password field prompt and echo setting, typically called by the PAM helper.

```APIDOC
## void CDialog::setPrompt(const std::string& text, bool echo)

### Description
Updates the password field prompt and echo setting. Called by PAM helper when it needs input.

### Parameters
- **text** (const std::string&) - Required - Prompt text (e.g., "Password: ")
- **echo** (bool) - Required - If false, input is hidden; if true, input is visible

### Returns
- void

### Example
```cpp
dialog->setPrompt("Enter password: ", false);
```
```

--------------------------------

### Set Info

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Displays or clears informational text in the dialog.

```cpp
dialog->setInfo("Sending verification code...");
dialog->setInfo("");  // Clear it
```

--------------------------------

### Configure details section visibility

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Toggles the visibility of the details section in the authentication dialog. Set to 0 to hide the section and the toggle button.

```ini
general {
    show_details = 0
}
```

--------------------------------

### Accessing Configuration via CConfigManager

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

Retrieve the current configuration object using the global singleton pointer.

```cpp
const auto& cfg = g_pConfigManager->get();
int pw = cfg.passwordFieldWidth;
bool showDetails = cfg.showDetails;
```

--------------------------------

### BeginAuthentication Method Signature

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

The D-Bus method signature for initiating a PolicyKit authentication request.

```text
org.freedesktop.PolicyKit1.AuthenticationAgent.BeginAuthentication(
    s action_id,
    s message,
    s icon_name,
    a{ss} details,
    s cookie,
    a(s a{s v}) identities
) -> ()
```

--------------------------------

### Submit Authentication Response

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Sends the provided password string to the active PAM helper process. Write errors are handled silently.

```cpp
listener.submitResponse("my_password");
```

--------------------------------

### void CAgent::submitPassword(const std::string& password)

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Submits the user-entered password to the PAM helper process.

```APIDOC
## void CAgent::submitPassword(const std::string& password)

### Description
Submits the user-entered password to the PAM helper process by writing to stdin.

### Parameters
- **password** (const std::string&) - Required - User-entered password or response.

### Returns
- **void**

### Example
```cpp
g_pAgent->submitPassword("user_password_123");
```
```

--------------------------------

### Handle PAM_PROMPT_ECHO_OFF

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Requests hidden input from the user. The agent responds by writing the password to stdin.

```text
PAM_PROMPT_ECHO_OFF <prompt_text>
```

```text
PAM_PROMPT_ECHO_OFF Password:
PAM_PROMPT_ECHO_OFF Enter Old Password:
```

```text
<password>
```

--------------------------------

### Submit a password to the PAM helper

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Writes the provided password string to the helper process stdin followed by a newline. Does not clear the input field automatically.

```cpp
// Called when user presses Enter in the password field
g_pAgent->submitPassword("user_password_123");
```

--------------------------------

### Normalize PAM prompt text in C++

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Removes trailing whitespace and colons from prompt strings to ensure clean UI display.

```cpp
std::string newPrompt = text;
while (!newPrompt.empty() && (newPrompt.back() == ' ' || newPrompt.back() == '\t'))
    newPrompt.pop_back();
if (!newPrompt.empty() && newPrompt.back() == ':')
    newPrompt.pop_back();
while (!newPrompt.empty() && (newPrompt.back() == ' ' || newPrompt.back() == '\t'))
    newPrompt.pop_back();
```

--------------------------------

### Handle PAM_TEXT_INFO

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Displays informational text to the user without requiring a response.

```text
PAM_TEXT_INFO <message_text>
```

```text
PAM_TEXT_INFO Please wait for 2FA code...
PAM_TEXT_INFO Your password expires in 7 days.
```

--------------------------------

### Check Socket Availability

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Verify if the polkit-agent-helper socket is active on a systemd-based system.

```bash
systemctl status polkit-agent-helper.socket
```

--------------------------------

### Minimal Configuration Override

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Sets only the password field width while retaining default values for all other settings.

```Hyprlang
general {
    password_field_width = 300
}
```

--------------------------------

### Configure authentication window width

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Sets the width of the authentication dialog window, constrained between 460 and 600 pixels.

```ini
general {
    window_width = 600
}
```

--------------------------------

### Invoke Fork Mode Helper

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

In fork mode, the helper is executed with the identity as an argument, followed by the cookie via stdin.

```bash
polkit-agent-helper-1 <identity>
```

```text
<cookie>
```

```bash
exec polkit-agent-helper-1 alice
```

```text
12345abcde
```

--------------------------------

### Parse PAM message prefixes in C++

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Uses prefix matching to identify PAM message types from helper stdout. The space after the tag is mandatory for correct parsing.

```cpp
if (line.starts_with("PAM_PROMPT_ECHO_OFF ")) {
    // Extract text after "PAM_PROMPT_ECHO_OFF "
    prompt_text = line.substr(20);
    // Handle echo=false case
}
```

--------------------------------

### Define Socket Mode Preamble

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

The agent sends identity and cookie information before the first prompt in socket mode.

```text
<identity>
<cookie>
```

```text
alice
12345abcde
```

--------------------------------

### Set Prompt

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Updates the password field prompt and echo setting. Input is hidden if echo is false.

```cpp
dialog->setPrompt("Enter password: ", false);
// Field now shows password mode, placeholder "Enter password"

dialog->setPrompt("Enter verification code: ", true);
// Field now shows visible mode for token input
```

--------------------------------

### Select Authentication Identity

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Switches the authentication identity and restarts the helper process. The identity string must exist within the current request's identity list.

```cpp
listener.selectIdentity("unix-user:0");
```

--------------------------------

### Manage hyprpolkitagent service status

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/configuration.md

Commands to check, restart, or enable the user service.

```bash
systemctl --user status hyprpolkitagent
systemctl --user restart hyprpolkitagent
systemctl --user enable hyprpolkitagent
```

--------------------------------

### CAgent::onInfo

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Displays informational text in the authentication dialog.

```APIDOC
## void CAgent::onInfo(const std::string& text)

### Description
Displays informational text in the dialog, such as status updates or validation messages.

### Parameters
- **text** (const std::string&) - Required - Informational message to display.

### Returns
- void

### Example
```cpp
g_pAgent->onInfo("Validating credentials...");
```
```

--------------------------------

### RegisterAuthenticationAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Registers the authentication agent with the PolicyKit Authority during startup.

```APIDOC
## org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent

### Description
Called during startup to register the application as an authentication agent with the PolicyKit Authority.

### Parameters
- **subject** ((s a{s v})) - Required - Session subject (kind="unix-session", properties={"session-id": STRING})
- **locale** (s) - Required - Locale string (from $LANG env, or empty)
- **object_path** (o) - Required - Agent object path (/org/hyprland/PolicyKit1/AuthenticationAgent)
```

--------------------------------

### CAgent::onRequest

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Updates the password field prompt and configures input echo settings.

```APIDOC
## void CAgent::onRequest(const std::string& prompt, bool echo)

### Description
Updates the password field prompt based on PAM helper output. Displays a prompt to the user and configures whether input should be echoed.

### Parameters
- **prompt** (const std::string&) - Required - Prompt text from PAM helper.
- **echo** (bool) - Required - If false, input is hidden; if true, input is visible.

### Returns
- void

### Example
```cpp
g_pAgent->onRequest("Enter password: ", false);
```
```

--------------------------------

### Process authentication request

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Passes a populated authentication request to the agent for UI display.

```cpp
CPolkitListener::SAuthRequest req = { /* populated from D-Bus */ };
g_pAgent->beginAuth(req);
```

--------------------------------

### CPolkitListener::registerAgent

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Registers the authentication agent with the system D-Bus and PolicyKit Authority, integrating with the provided backend event loop.

```APIDOC
## Method: registerAgent

### Description
Connects to the system D-Bus, registers as a PolicyKit authentication agent for the current session, and sets up event loop integration.

### Signature
`bool CPolkitListener::registerAgent(Hyprutils::Memory::CSharedPointer<Hyprtoolkit::IBackend> backend)`

### Parameters
- **backend** (CSharedPointer<IBackend>) - Required - Hyprtoolkit backend for event loop integration

### Returns
- **bool** - true if registration succeeded; false if D-Bus connection, session lookup, or PolicyKit registration failed.

### Example
```cpp
auto backend = IBackend::create();
CPolkitListener listener;
if (!listener.registerAgent(backend)) {
    // Failed to register; exit
    return false;
}
// Now ready to receive authentication requests
```
```

--------------------------------

### Define SHPAConfig structure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

The configuration structure defining the available settings and their default values.

```cpp
struct SHPAConfig {
    int  passwordFieldWidth = 340;
    int  windowWidth        = 520;
    int  windowHeight       = 440;
    bool showDetails        = true;
};
```

--------------------------------

### CConfigManager Global Singleton Declaration

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CConfigManager.md

The global pointer used to access the configuration manager instance, initialized during agent startup.

```cpp
inline CConfigManager* g_pConfigManager = nullptr;
```

--------------------------------

### void CAgent::onError(const std::string& text)

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Displays an error message in the authentication dialog.

```APIDOC
## void CAgent::onError(const std::string& text)

### Description
Displays an error message in the dialog (e.g., "Authentication failed", "Invalid password").

### Parameters
- **text** (const std::string&) - Required - Error message to display.

### Returns
- **void**

### Example
```cpp
g_pAgent->onError("Password incorrect. Try again.");
```
```

--------------------------------

### submitResponse

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Sends the user-entered password to the active PAM helper process.

```APIDOC
## void CPolkitListener::submitResponse(const std::string& password)

### Description
Sends the user-entered password to the active PAM helper process. Writes the password followed by a newline to the helper's stdin.

### Parameters
- **password** (const std::string&) - Required - User response (password or other PAM prompt response)

### Returns
- **void**

### Example
```cpp
listener.submitResponse("my_password");
```
```

--------------------------------

### Write to helper stdin

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Performs a single write operation to the helper stdin without retries or buffering, relying on pipe buffer capacity.

```cpp
(void)write(m_current->helper.stdinFd, line.data(), line.size());
```

--------------------------------

### void CDialog::setError(const std::string& text)

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Displays or clears an error message within the authentication dialog.

```APIDOC
## void CDialog::setError(const std::string& text)

### Description
Displays an error message in the dialog. If the provided text is non-empty, the error label is added to the status container; if empty, the error label is removed.

### Parameters
- **text** (const std::string&) - Required - The error message to display (e.g., "Password incorrect").

### Returns
- **void**

### Example
```cpp
dialog->setError("Invalid password. Try again.");
dialog->setError("");  // Clear it
```
```

--------------------------------

### Return Authentication Success or Cancellation

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Signals successful authentication or cancellation to PolicyKit by returning an empty result.

```cpp
m_current->reply->returnResults();
```

--------------------------------

### Access CAgent Listener

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Retrieves the D-Bus listener instance to submit authentication responses.

```cpp
auto& listener = g_pAgent->listener();
listener.submitResponse("password");
```

--------------------------------

### Process helper stdout buffer

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Reads helper output into a buffer and processes complete lines delimited by newlines.

```cpp
while ((n = read(cur->helper.stdoutFd, buf, sizeof(buf))) > 0)
    cur->helper.buffer.append(buf, (size_t)n);

while (true) {
    const auto pos = cur->helper.buffer.find('\n');
    if (pos == std::string::npos)
        break;  // Wait for more data
    std::string line = cur->helper.buffer.substr(0, pos);
    cur->helper.buffer.erase(0, pos + 1);
    handleLine(*cur, line);
}
```

--------------------------------

### Handle Authentication Status

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Indicates the final result of the authentication process.

```text
SUCCESS
```

```text
FAILURE
```

--------------------------------

### CAgent::listener

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Retrieves the D-Bus listener instance for authentication requests.

```APIDOC
## CPolkitListener& CAgent::listener()

### Description
Returns a reference to the D-Bus listener that receives polkit authentication requests.

### Returns
- **CPolkitListener&** - The internal listener instance

### Example
```cpp
auto& listener = g_pAgent->listener();
listener.submitResponse("password");
```
```

--------------------------------

### Handle socket connection failure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Checks for socket connection errors, excluding EINPROGRESS, to determine if the helper is unreachable.

```cpp
if (connect(sockFd, &addr, sizeof(addr)) < 0 && errno != EINPROGRESS) {
    // Socket unreachable
    return false;
}
```

--------------------------------

### CAgent::selectIdentity

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Switches the authentication identity, restarts the PAM helper, and clears pending messages.

```APIDOC
## void CAgent::selectIdentity(const std::string& identityString)

### Description
Switches to a different identity (user) for authentication. Kills the current helper and restarts it for the new identity.

### Parameters
- **identityString** (const std::string&) - Required - Raw identity string (e.g., "unix-user:1000")

### Returns
- **void**

### Example
```cpp
g_pAgent->selectIdentity("unix-user:0");
```
```

--------------------------------

### Successful Authentication Protocol Flow

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Sequence of interactions between the PolicyKit Authority, the agent, and the PAM helper during a successful authentication.

```text
1. PolicyKit Authority -> Agent.BeginAuthentication()
   ↓
2. Agent displays dialog and starts PAM helper
   ↓
3. PAM Helper -> Agent (stdin): <identity>\n<cookie>\n
   ↓
4. PAM Helper -> Agent (stdout): PAM_PROMPT_ECHO_OFF "Password: "
   ↓
5. Agent -> Dialog.setPrompt()
   ↓
6. User enters password and presses Enter
   ↓
7. Agent -> PAM Helper (stdin): <password>\n
   ↓
8. PAM Helper validates password with kernel/directory
   ↓
9. PAM Helper -> Agent (stdout): SUCCESS
   ↓
10. Agent -> Dialog.close()
    ↓
11. Agent -> BeginAuthentication result: returnResults() [success]
    ↓
12. PolicyKit Authority allows the action
```

--------------------------------

### Return Authentication Failure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Signals an authentication failure to PolicyKit by returning a specific D-Bus error.

```cpp
m_current->reply->returnError(
    sdbus::Error{
        sdbus::Error::Name{"org.freedesktop.PolicyKit1.Error.Failed"},
        "Authentication failed"
    }
);
```

--------------------------------

### void CDialog::close()

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Closes the dialog window and releases the associated window object.

```APIDOC
## void CDialog::close()

### Description
Closes the window and releases the window object.

### Parameters
- None

### Returns
- void

### Example
```cpp
dialog->close();
```
```

--------------------------------

### End Authentication Session

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Closes the current authentication dialog and cleans up resources.

```cpp
g_pAgent->endAuth();
// Dialog is gone; agent is ready for the next request
```

--------------------------------

### Destroy CPolkitListener

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Performs cleanup of D-Bus connections, agent registration, helper processes, and file descriptor watches.

```cpp
CPolkitListener::~CPolkitListener()
```

--------------------------------

### Display an error message in the authentication dialog

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Updates the error label with the provided text. The error persists until a new message is set or the dialog is closed.

```cpp
g_pAgent->onError("Password incorrect. Try again.");
```

--------------------------------

### Define SActiveAuth structure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Internal structure representing an in-progress authentication session. This is a private structure used by the PolkitListener.

```cpp
struct SActiveAuth {
    SAuthRequest                     req;
    std::unique_ptr<sdbus::Result<>> reply;
    int                              selectedIdx = 0;
    SHelperProc                      helper;
};
```

--------------------------------

### Ignore SIGPIPE signal

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Prevents agent crashes when writing to a helper process that exits unexpectedly.

```cpp
signal(SIGPIPE, SIG_IGN);
```

--------------------------------

### selectIdentity

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Switches to a different identity within the current authentication request.

```APIDOC
## void CPolkitListener::selectIdentity(const std::string& identityString)

### Description
Switches to a different identity within the current authentication request. It validates the identity, updates the index, and restarts the helper with the new identity.

### Parameters
- **identityString** (const std::string&) - Required - Raw identity string (e.g., unix-user:1000)

### Returns
- **void**

### Example
```cpp
listener.selectIdentity("unix-user:0");
```
```

--------------------------------

### Display Informational Text

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Updates the dialog's info label with the provided message.

```cpp
g_pAgent->onInfo("Validating credentials...");
```

--------------------------------

### void CAgent::cancel()

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Cancels the current authentication request.

```APIDOC
## void CAgent::cancel()

### Description
Cancels the current authentication request without submitting a password, closes the dialog, and notifies polkit.

### Returns
- **void**

### Example
```cpp
g_pAgent->cancel();
```
```

--------------------------------

### CAgent::endAuth

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Closes and cleans up the current authentication dialog.

```APIDOC
## void CAgent::endAuth()

### Description
Closes and cleans up the current authentication dialog. This method closes the window if it is open and releases the dialog object.

### Parameters
- None

### Returns
- void

### Example
```cpp
g_pAgent->endAuth();
```
```

--------------------------------

### Define SAuthRequest structure

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Structure containing all information required for a PolicyKit authentication request.

```cpp
struct SAuthRequest {
    std::string                                      actionId;
    std::string                                      message;
    std::string                                      iconName;
    std::string                                      cookie;
    std::vector<SIdentity>                           identities;
    std::string                                      command;
    std::vector<std::pair<std::string, std::string>> details;
    std::string                                      vendor;
    std::string                                      vendorUrl;
};
```

--------------------------------

### Cancel the current authentication request

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Closes the active authentication dialog and notifies polkit that the request has been cancelled.

```cpp
// Called when user presses Escape or clicks the close button
g_pAgent->cancel();
```

--------------------------------

### Check session lock status

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/dbus-interface.md

Verifies the LockedHint property on the logind session object before processing authentication requests.

```cpp
bool CPolkitListener::isSessionLocked()
```

--------------------------------

### Cancel Authentication Request

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CPolkitListener.md

Terminates the current authentication helper and closes the associated dialog. This operation is ignored if no authentication is currently in progress.

```cpp
listener.cancelCurrent();
```

--------------------------------

### Handle PAM_ERROR_MSG

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/pam-protocol.md

Displays an error message to the user.

```text
PAM_ERROR_MSG <error_text>
```

```text
PAM_ERROR_MSG Invalid password. Try again.
PAM_ERROR_MSG Account locked. Contact administrator.
```

--------------------------------

### Close Dialog

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Closes the window and releases the window object.

```cpp
dialog->close();
// Window is gone; dialog is ready for cleanup
```

--------------------------------

### Define Global CAgent Instance

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CAgent.md

Declares the global unique pointer for the CAgent singleton.

```cpp
inline std::unique_ptr<CAgent> g_pAgent;
```

--------------------------------

### Set or clear error message in CDialog

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/api-reference/CDialog.md

Updates the error label in the status container. Passing an empty string clears the existing error.

```cpp
dialog->setError("Invalid password. Try again.");
dialog->setError("");  // Clear it
```

--------------------------------

### SHelperProc Structure Definition

Source: https://github.com/hyprwm/hyprpolkitagent/blob/main/_autodocs/types.md

Internal structure used to track the state of a PAM helper process.

```cpp
struct SHelperProc {
    eHelperMode mode      = HELPER_NONE;
    pid_t       pid       = -1;
    int         stdinFd   = -1;
    int         stdoutFd  = -1;
    bool        gotPrompt = false;
    bool        triedFork = false;
    std::string buffer;
};
```