A PolicyKit authentication agent for Phosphor-based desktop shells. More...
#include <PhosphorServicePolkit/PolkitAgent.h>
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. | |
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.
|
strong |
|
explicit |
Agent for the current session, at the default object path.
| 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.
|
override |
|
nodiscard |
The authentication request polkit is currently waiting on, or null.
A dialog binds this; at most one is active (polkit serialises).
|
signal |
| 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.
|
signal |
The active request ended with none remaining (declined here, or withdrawn by polkit).
|
signal |
The PAM conversation finished; gainedAuthorization is true when the user authenticated successfully.
|
signal |
PAM reported an error (e.g. "Authentication failure") to show the user.
|
signal |
PAM reported an informational message to show the user.
|
signal |
A new authentication request arrived (also reflected in activeRequest).
|
nodiscard |
| 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.
|
nodiscard |
|
staticnodiscard |
The default D-Bus object path the agent exports at.
|
nodiscard |
|
nodiscard |
|
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).
| 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.
|
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).
|
signal |
| 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.
| void PhosphorServicePolkit::PolkitAgent::retry | ( | ) |
Retry an unavailable conversation, within the request's attempt limit.
| void PhosphorServicePolkit::PolkitAgent::selectIdentity | ( | int | index | ) |
Restart the same request as another offered identity.
The previous conversation is cancelled without resolving the polkit result.
|
signal |