Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorServicePolkit::PolkitAgent Class Reference

A PolicyKit authentication agent for Phosphor-based desktop shells. More...

#include <PhosphorServicePolkit/PolkitAgent.h>

Inheritance diagram for PhosphorServicePolkit::PolkitAgent:
[legend]

Public Types

enum class  Phase {
  Idle , Starting , Prompt , Checking ,
  Unavailable , Failed , Success , Cancelled
}

Signals

void registeredChanged ()
void activeRequestChanged ()
void stateChanged ()
void authenticationRequested (PhosphorServicePolkit::AuthRequest *request)
 A new authentication request arrived (also reflected in activeRequest).
void promptRequested (const QString &prompt, bool echo)
 PAM is asking for input: answer it with respond().
void authenticationCompleted (bool gainedAuthorization)
 The PAM conversation finished; gainedAuthorization is true when the user authenticated successfully.
void authenticationError (const QString &text)
 PAM reported an error (e.g. "Authentication failure") to show the user.
void authenticationInfo (const QString &text)
 PAM reported an informational message to show the user.
void authenticationCancelled ()
 The active request ended with none remaining (declined here, or withdrawn by polkit).

Public Member Functions

 PolkitAgent (QObject *parent=nullptr)
 Agent for the current session, at the default object path.
 PolkitAgent (QString sessionId, QString objectPath, QObject *parent=nullptr)
 Dependency-injected: register for an explicit session id at an explicit object path (tests pass a synthetic session so registration is exercised without owning the real one).
 ~PolkitAgent () override
bool registered () const
 True once this process is the registered authentication agent for its session.
bool registerAgent ()
 Register with polkitd as the session's authentication agent.
AuthRequest * activeRequest () const
 The authentication request polkit is currently waiting on, or null.
Phase phase () const
bool inputReady () const
bool busy () const
bool canRetry () const
void authenticate ()
 Begin authenticating the active request as its selectedIdentity: starts the PAM conversation, after which activeRequest's prompt updates and the user's answer goes back via respond().
void respond (const QString &response)
 Answer the active PAM prompt.
void selectIdentity (int index)
 Restart the same request as another offered identity.
void retry ()
 Retry an unavailable conversation, within the request's attempt limit.
void cancel ()
 Decline the active request: it completes without authorization and clears (aborting any running PAM conversation).

Static Public Member Functions

static QString defaultObjectPath ()
 The default D-Bus object path the agent exports at.

Detailed Description

A PolicyKit authentication agent for Phosphor-based desktop shells.

When an application requests a privileged action, polkitd calls into the agent registered for the session; the agent drives the PAM conversation that authenticates the user. This class is that agent. It wraps polkit-qt6's Agent::Listener privately, so the public surface stays a clean QObject with no polkit-qt types: a consumer binds the request + a respond path and never touches polkit-qt directly.

Registration is explicit (registerAgent()), not done in the constructor: becoming the session's agent intercepts every authentication, so it is an opt-in step a shell or the CLI demo takes deliberately. Exactly one agent serves a session, so when the desktop's agent (KDE / GNOME) already holds it registerAgent() fails and the object stays inert (registered() == false), mirroring the name-conflict-is-inert shape of phosphor-service-notifications.

initiateAuthentication from polkit is decoded into a typed AuthRequest surfaced as activeRequest; authenticate() then drives the Agent::Session PAM conversation (prompt -> respond() -> completed), with cancel() and polkit's withdrawal both resolving polkit's result exactly once.

Member Enumeration Documentation

◆ Phase

Enumerator
Idle 
Starting 
Prompt 
Checking 
Unavailable 
Failed 
Success 
Cancelled 

Constructor & Destructor Documentation

◆ PolkitAgent() [1/2]

PhosphorServicePolkit::PolkitAgent::PolkitAgent ( QObject * parent = nullptr)
explicit

Agent for the current session, at the default object path.

◆ PolkitAgent() [2/2]

PhosphorServicePolkit::PolkitAgent::PolkitAgent ( QString sessionId,
QString objectPath,
QObject * parent = nullptr )

Dependency-injected: register for an explicit session id at an explicit object path (tests pass a synthetic session so registration is exercised without owning the real one).

An empty sessionId means the current session, resolved at registration time.

◆ ~PolkitAgent()

PhosphorServicePolkit::PolkitAgent::~PolkitAgent ( )
override

Member Function Documentation

◆ activeRequest()

AuthRequest * PhosphorServicePolkit::PolkitAgent::activeRequest ( ) const
nodiscard

The authentication request polkit is currently waiting on, or null.

A dialog binds this; at most one is active (polkit serialises).

◆ activeRequestChanged

void PhosphorServicePolkit::PolkitAgent::activeRequestChanged ( )
signal

◆ authenticate()

void PhosphorServicePolkit::PolkitAgent::authenticate ( )

Begin authenticating the active request as its selectedIdentity: starts the PAM conversation, after which activeRequest's prompt updates and the user's answer goes back via respond().

A no-op with no active request or once a conversation is already running. Q_INVOKABLE for a UI.

◆ authenticationCancelled

void PhosphorServicePolkit::PolkitAgent::authenticationCancelled ( )
signal

The active request ended with none remaining (declined here, or withdrawn by polkit).

◆ authenticationCompleted

void PhosphorServicePolkit::PolkitAgent::authenticationCompleted ( bool gainedAuthorization)
signal

The PAM conversation finished; gainedAuthorization is true when the user authenticated successfully.

◆ authenticationError

void PhosphorServicePolkit::PolkitAgent::authenticationError ( const QString & text)
signal

PAM reported an error (e.g. "Authentication failure") to show the user.

◆ authenticationInfo

void PhosphorServicePolkit::PolkitAgent::authenticationInfo ( const QString & text)
signal

PAM reported an informational message to show the user.

◆ authenticationRequested

void PhosphorServicePolkit::PolkitAgent::authenticationRequested ( PhosphorServicePolkit::AuthRequest * request)
signal

A new authentication request arrived (also reflected in activeRequest).

◆ busy()

bool PhosphorServicePolkit::PolkitAgent::busy ( ) const
nodiscard

◆ cancel()

void PhosphorServicePolkit::PolkitAgent::cancel ( )

Decline the active request: it completes without authorization and clears (aborting any running PAM conversation).

Q_INVOKABLE for a UI / CLI; never exported on any bus.

◆ canRetry()

bool PhosphorServicePolkit::PolkitAgent::canRetry ( ) const
nodiscard

◆ defaultObjectPath()

QString PhosphorServicePolkit::PolkitAgent::defaultObjectPath ( )
staticnodiscard

The default D-Bus object path the agent exports at.

◆ inputReady()

bool PhosphorServicePolkit::PolkitAgent::inputReady ( ) const
nodiscard

◆ phase()

Phase PhosphorServicePolkit::PolkitAgent::phase ( ) const
nodiscard

◆ promptRequested

void PhosphorServicePolkit::PolkitAgent::promptRequested ( const QString & prompt,
bool echo )
signal

PAM is asking for input: answer it with respond().

This is an EVENT, not a property change, so it fires once per request including a same-text retry after a wrong answer (which activeRequest's change-guarded prompt would not re-notify). echo is false for secrets (do not echo input).

◆ registerAgent()

bool PhosphorServicePolkit::PolkitAgent::registerAgent ( )

Register with polkitd as the session's authentication agent.

Returns registered(). A no-op once registered. Q_INVOKABLE so a shell/CLI can opt in from QML.

◆ registered()

bool PhosphorServicePolkit::PolkitAgent::registered ( ) const
nodiscard

True once this process is the registered authentication agent for its session.

False until registerAgent() succeeds, or when another agent already holds the session (see class docs).

◆ registeredChanged

void PhosphorServicePolkit::PolkitAgent::registeredChanged ( )
signal

◆ respond()

void PhosphorServicePolkit::PolkitAgent::respond ( const QString & response)

Answer the active PAM prompt.

The response is passed straight to PAM and is never stored, logged, or echoed by this library. Q_INVOKABLE for a UI.

◆ retry()

void PhosphorServicePolkit::PolkitAgent::retry ( )

Retry an unavailable conversation, within the request's attempt limit.

◆ selectIdentity()

void PhosphorServicePolkit::PolkitAgent::selectIdentity ( int index)

Restart the same request as another offered identity.

The previous conversation is cancelled without resolving the polkit result.

◆ stateChanged

void PhosphorServicePolkit::PolkitAgent::stateChanged ( )
signal

The documentation for this class was generated from the following file:
  • phosphor-service-polkit/include/PhosphorServicePolkit/PolkitAgent.h